{"meta":{"title":"Руководство по отладке","intro":"Это руководство охватывает распространённые проблемы и методы отладки для Copilot SDK на всех поддерживаемых языках.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ru/copilot","title":"GitHub Copilot"},{"href":"/ru/copilot/how-tos","title":"Инструкции"},{"href":"/ru/copilot/how-tos/copilot-sdk","title":"Второй пилот SDK"},{"href":"/ru/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/ru/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"Отладка"}],"documentType":"article"},"body":"# Руководство по отладке\n\nЭто руководство охватывает распространённые проблемы и методы отладки для Copilot SDK на всех поддерживаемых языках.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Оглавление\n\n* [Включить отладочный лог](#enable-debug-logging)\n* [Распространённые проблемы](#common-issues)\n* [Отладка серверов MCP](#mcp-server-debugging)\n* [Проблемы с подключением](#connection-issues)\n* [Проблемы с выполнением инструментов](#tool-execution-issues)\n* [Platform-Specific Проблемы](#platform-specific-issues)\n\n## Включение ведения журнала отладки\n\nПервым шагом в отладке является возможность подробного ведения логирования, чтобы видеть, что происходит под капотом.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n  logLevel: \"debug\",  // Options: \"none\", \"error\", \"warning\", \"info\", \"debug\", \"all\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient(log_level=\"debug\")\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nimport copilot \"github.com/github/copilot-sdk/go\"\n\nclient := copilot.NewClient(&copilot.ClientOptions{\n    LogLevel: \"debug\",\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n<!-- docs-validate: skip -->\n\n```csharp\nusing GitHub.Copilot;\nusing Microsoft.Extensions.Logging;\n\n// Using ILogger\nvar loggerFactory = LoggerFactory.Create(builder =>\n{\n    builder.SetMinimumLevel(LogLevel.Debug);\n    builder.AddConsole();\n});\n\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    LogLevel = \"debug\",\n    Logger = loggerFactory.CreateLogger<CopilotClient>()\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setLogLevel(\"debug\")\n);\n```\n\n</div>\n\n</div>\n\n### Каталог журналов\n\nCLI записывает журналы в каталог. Вы можете указать пользовательское местоположение:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliArgs: [\"--log-dir\", \"/path/to/logs\"],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\n# The Python SDK does not currently support passing extra CLI arguments.\n# Logs are written to the default location or can be configured via\n# the CLI when running in server mode.\n```\n\n> \\[!NOTE]\n> Конфигурация логирования Python SDK ограничена. Для продвинутой логировки запускайте CLI вручную с `--log-dir` .`RuntimeConnection.for_uri(...)`\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{\n        Args: []string{\"--log-dir\", \"/path/to/logs\"},\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    Connection = RuntimeConnection.ForStdio(args: new[] { \"--log-dir\", \"/path/to/logs\" })\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n<!-- docs-validate: skip -->\n\n```java\n// The Java SDK does not currently support passing extra CLI arguments.\n// For custom log directories, run the CLI manually with --log-dir\n// and connect via cliUrl.\n```\n\n</div>\n\n</div>\n\n## Распространенные проблемы\n\n### \"CLI не найден\" / \"Copilot: команда не найдена\"\n\n**Причина:** Copilot CLI не установлен и не установлен в PATH.\n\n**Solution:**\n\n1. Установка CLI: [руководство по установке](/ru/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. Проверьте установку:\n\n   ```bash\n   copilot --version\n   ```\n\n3. Или укажите полный путь:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliPath: \"/usr/local/bin/copilot\",\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nclient = CopilotClient({\"cli_path\": \"/usr/local/bin/copilot\"})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    CliPath = \"/usr/local/bin/copilot\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setCliPath(\"/usr/local/bin/copilot\")\n);\n```\n\n</div>\n\n</div>\n\n### «Не подтвержено»\n\n**Причина:** CLI не аутентифицирован с GitHub.\n\n**Solution:**\n\n1. Аутентифицировать CLI:\n\n   ```bash\n   copilot auth login\n   ```\n\n2. Или программно предоставить токен:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  gitHubToken: process.env.GITHUB_TOKEN,\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nimport os\nclient = CopilotClient({\"github_token\": os.environ.get(\"GITHUB_TOKEN\")})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    GitHubToken: os.Getenv(\"GITHUB_TOKEN\"),\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    GitHubToken = Environment.GetEnvironmentVariable(\"GITHUB_TOKEN\")\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setGitHubToken(System.getenv(\"GITHUB_TOKEN\"))\n);\n```\n\n</div>\n\n</div>\n\n### «Сессия не найдена»\n\n**Причина:** Попытка использовать сессию, которая была уничтожена или не существует.\n\n**Solution:**\n\n1. Убедитесь, что вы не вызываете методы после `disconnect()`:\n\n   ```typescript\n   await session.disconnect();\n   // Don't use session after this!\n   ```\n\n2. Для возобновления сессий проверьте наличие идентификатора сессии:\n\n   ```typescript\n   const sessions = await client.listSessions();\n   console.log(\"Available sessions:\", sessions);\n   ```\n\n### \"Соединение отказано\" / \"ОТКАЗАНО\"\n\n**Причина:** Процесс CLI-сервера вылетел или не запустился.\n\n**Solution:**\n\n1. Проверьте, работает ли CLI самостоятельно:\n\n   ```bash\n   copilot --server --stdio\n   ```\n\n2. Проверьте на конфликты портов при использовании режима TCP:\n\n   ```typescript\n   const client = new CopilotClient({\n     useStdio: false,\n     port: 0,  // Use random available port\n   });\n   ```\n\n## Отладка серверов MCP\n\nСерверы MCP (Model Context Protocol) могут быть сложны в отладке. Для полных рекомендаций по отладке MCP смотрите специальный **[раздел AUTOTITLE](/ru/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)**.\n\n### Быстрый чек-лист MCP\n\n* [ ] Исполняемый файл сервера MCP существует и работает независимо\n* [ ] Путь команды верен (используйте абсолютные пути)\n* [ ] Инструменты включены: `tools: [\"*\"]`\n* [ ] Сервер правильно отвечает на `initialize` запрос\n* [ ] Рабочая директория (`cwd`) устанавливается при необходимости\n\n### Тестирование сервера MCP\n\nПеред интеграцией с SDK убедитесь, что ваш MCP-сервер работает:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n```\n\nСм. [Руководство по отладке серверов MCP](/ru/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) для подробного устранения неполадок.\n\n## Проблемы с подключением\n\n### stdio против TCP режима\n\nSDK поддерживает два режима транспорта:\n\n| Режим                    | Description                                       | Вариант использования             |\n| ------------------------ | ------------------------------------------------- | --------------------------------- |\n| **Stdio** (по умолчанию) | CLI работает как подпроцесс, общается через трубы | Местное развитие, единый процесс  |\n| **TCP**                  | CLI работает отдельно, общается через TCP-сокет   | Несколько клиентов, удалённый CLI |\n\n**Режим Stdio (по умолчанию):**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: true,  // This is the default\n});\n```\n\n**Режим TCP:**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: false,\n  port: 8080,  // Or 0 for random port\n});\n```\n\n**Подключитесь к существующему серверу:**\n\n```typescript\nconst client = new CopilotClient({\n  cliUrl: \"localhost:8080\",  // Connect to running server\n});\n```\n\n### Диагностика сбоев соединения\n\n1. **Проверьте состояние клиента:**\n\n   ```typescript\n   console.log(\"Connection state:\", client.getState());\n   // Should be \"connected\" after start()\n   ```\n\n2. **Слушайте изменения в состоянии:**\n\n   ```typescript\n   client.on(\"stateChange\", (state) => {\n     console.log(\"State changed to:\", state);\n   });\n   ```\n\n3. **Проверьте, что процесс CLI запущен:**\n\n   ```bash\n   # Check for copilot processes\n   ps aux | grep copilot\n   ```\n\n## Проблемы с выполнением инструментов\n\n### Пользовательский инструмент не вызывается\n\n1. **Проверьте регистрацию инструмента:**\n\n   ```typescript\n   const session = await client.createSession({\n     tools: [myTool],\n   });\n\n   // Check registered tools\n   console.log(\"Registered tools:\", session.getTools?.());\n   ```\n\n2. **Check Tool Scheme is valid JSON Schema:**\n\n   ```typescript\n   const myTool = {\n     name: \"get_weather\",\n     description: \"Get weather for a location\",\n     parameters: {\n       type: \"object\",\n       properties: {\n         location: { type: \"string\", description: \"City name\" },\n       },\n       required: [\"location\"],\n     },\n     handler: async (args) => {\n       return { temperature: 72 };\n     },\n   };\n   ```\n\n3. **Убедитесь, что обработчик возвращает действительный результат:**\n\n   ```typescript\n   handler: async (args) => {\n     // Must return something JSON-serializable\n     return { success: true, data: \"result\" };\n     \n     // Don't return undefined or non-serializable objects\n   }\n   ```\n\n### Ошибки инструмента не появляются\n\nПодписывайтесь на события ошибок:\n\n```typescript\nsession.on(\"tool.execution_error\", (event) => {\n  console.error(\"Tool error:\", event.data);\n});\n\nsession.on(\"error\", (event) => {\n  console.error(\"Session error:\", event.data);\n});\n```\n\n## Проблемы, связанные с платформой\n\n### Windows\n\n1. **Сепараторы путей:** Используйте необработанные струны или прямые слэшы:\n\n   ```csharp\n   CliPath = @\"C:\\Program Files\\GitHub\\copilot.exe\"\n   // or\n   CliPath = \"C:/Program Files/GitHub/copilot.exe\"\n   ```\n\n2. **Разрешение PATHEXT:** SDK обрабатывает это автоматически, но если проблемы сохраняются:\n\n   ```csharp\n   // Explicitly specify .exe\n   Command = \"myserver.exe\"  // Not just \"myserver\"\n   ```\n\n3. **Консольное кодирование:** Убедитесь, что UTF-8 для правильной обработки JSON:\n\n   ```csharp\n   Console.OutputEncoding = System.Text.Encoding.UTF8;\n   ```\n\n### macOS\n\n1. **Проблемы с хранителями врат:** Если CLI заблокирован:\n\n   ```bash\n   xattr -d com.apple.quarantine /path/to/copilot\n   ```\n\n2. **Проблемы с PATH в GUI-приложениях:** GUI-приложения не могут наследовать PATH оболочки:\n\n   ```typescript\n   const client = new CopilotClient({\n     cliPath: \"/opt/homebrew/bin/copilot\",  // Full path\n   });\n   ```\n\n### Linux\n\n1. **Проблемы с разрешениями:**\n\n   ```bash\n   chmod +x /path/to/copilot\n   ```\n\n2. **Отсутствующие библиотеки:** Проверьте наличие обязательных общих библиотек:\n\n   ```bash\n   ldd /path/to/copilot\n   ```\n\n## Получение помощи\n\nЕсли вы всё ещё застряли:\n\n1. **Собирайте отладочную информацию:**\n   * Версия пакета SDK\n   * Версия CLI (`copilot --version`)\n   * Операционная система\n   * Логи отладки\n   * Код минимального воспроизведения\n\n2. **Поиск существующих номеров:**[GitHub Проблемы](https://github.com/github/copilot-sdk/issues)\n\n3. **Откройте новый выпуск** с собранной информацией\n\n## См. также\n\n* [Создайте своё первое приложение на базе Copilot](/ru/copilot/how-tos/copilot-sdk/getting-started)\n* [Использование MCP-серверов с SDK GitHub Copilot](/ru/copilot/how-tos/copilot-sdk/features/mcp) — конфигурация и настройка MCP\n* [Руководство по отладке серверов MCP](/ru/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) — подробное устранение неполадок MCP\n* [Справочник по интерфейсам API](https://github.com/github/copilot-sdk)"}