# Совместимость SDK и CLI В этом документе описаны, какие функции Copilot CLI доступны через SDK и какие являются только CLI. ## Обзор SDK Copilot взаимодействует с CLI через JSON-RPC протокол. Функции должны быть явно раскрыты через этот протокол, чтобы быть доступными в SDK. Многие интерактивные функции CLI специфичны для терминала и недоступны программно. ## Сравнение функций ### ✅ Доступно в формате SDK | Функция | Метод SDK | Notes | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Управление сеансами** | | | | | | | | Создание сеанса | `createSession()` | Полная поддержка конфигурации | | Сессия резюме | `resumeSession()` | С бесконечными сессионными рабочими пространствами | | Завершить сеанс. | `disconnect()` | Выпуск ресурсов в памяти | | Сессия *уничтожения (устарела)* | `destroy()` | Вместо нее следует использовать `disconnect()`. | | Удаление сеанса | `deleteSession()` | Извлечение из хранения | | Список сеансов | `listSessions()` | Все сохранённые сессии | | Получите последнюю сессию | `getLastSessionId()` | Краткое резюме | | Сессия на переднем плане | `getForegroundSessionId()` | Многосессионная координация | | Задайте сессию на переднем плане | `setForegroundSessionId()` | Многосессионная координация | | **Messaging** | | | | | | | | Отправить сообщение | `send()` | С приложениями | | Отправь и жди | `sendAndWait()` | Блоки до завершения | | Рулевое управление (режим мгновенности) | `send({ mode: "immediate" })` | Ввод в середине поворота без прекращения | | Очередь (режим очереди) | `send({ mode: "enqueue" })` | Буфер для последовательной обработки (по умолчанию) | | Вложенные файлы | `send({ attachments: [{ type: "file", path }] })` | Изображения автоматически кодируются и изменяются в размере | | Вложения в каталог | `send({ attachments: [{ type: "directory", path }] })` | Прикрепить контекст каталога | | Узнать историю | `getEvents()` | Все сессионные мероприятия | | Отмена | `abort()` | Отменить запрос на борт | | **Инструменты** | | | | | | | | Регистрируйте пользовательские инструменты | `registerTools()` | Полная поддержка JSON Schema | | Контроль прав на инструмент | | | | `onPreToolUse` Крюк | Разрешить/отрицать/просить | | | Модификация результатов инструмента | | | | `onPostToolUse` Крюк | Результаты преобразования | | | Доступные/исключённые инструменты | | | | `availableTools`, `excludedTools` конфигурация | Инструменты фильтрации | | | **Модели** | | | | | | | | Перечисление моделей | `listModels()` | С возможностями, биллингом, политикой | | Модель множества (на момент создания) | | | | `model` Конфигурация в сессии | За сессию | | | Модель Switch (в середине сессии) | `session.setModel()` | Также через `session.rpc.model.switchTo()` | | Получите актуальную модель | `session.rpc.model.getCurrent()` | Активная модель запроса | | Усилие по рассуждению | | | | `reasoningEffort` конфигурация | Для поддерживаемых моделей | | | **Режим агента** | | | | | | | | Включите текущий режим | `session.rpc.mode.get()` | Возвращает текущий режим | | Режим постановки | `session.rpc.mode.set()` | Переключение между режимами | | **Управление планами** | | | | | | | | Читать план | `session.rpc.plan.read()` | Получайте plan.md контент и путь | | План обновления | `session.rpc.plan.update()` | Пишите plan.md контент | | Удалить план | `session.rpc.plan.delete()` | Удалите plan.md | | **Файлы рабочей области** | | | | | | | | Список файлов рабочего пространства | `session.rpc.workspace.listFiles()` | Файлы в рабочем пространстве сессии | | Читать файл рабочего пространства | `session.rpc.workspace.readFile()` | Чтение содержимого файла | | Создать файл рабочего пространства | `session.rpc.workspace.createFile()` | Создать файл в рабочем пространстве | | **Authentication** | | | | | | | | Получить статус аутентификации | `getAuthStatus()` | Проверьте состояние входа | | Используйте токен | параметр `gitHubToken` | Программная аутентификация | | **Связь** | | | | | | | | Пинг | `client.ping()` | Проверка состояния с таймметкой сервера | | Получить статус сервера | `client.getStatus()` | Версия протокола и информация о сервере | | **Серверы MCP** | | | | | | | | Локальные/stdio серверы | | | | `mcpServers` конфигурация | Процессы появления | | | Удалённый HTTP/SSE | | | | `mcpServers` конфигурация | Подключение к службам | | | **Хуки** | | | | | | | | До использования инструментов | `onPreToolUse` | Разрешение, изменение args | | После использования инструмента (успех) | `onPostToolUse` | Изменить результаты | | После использования инструмента (неудача) | `onPostToolUseFailure` | Наблюдайте за неудачными вызовами инструментов, вводите инструкции по повторным попыткам | | Запрос пользователя | `onUserPromptSubmitted` | Подсказки изменения | | Начало/окончание сессии | | | | `onSessionStart`, `onSessionEnd` | Жизненный цикл с источником/причиной | | | Обработка ошибок | `onErrorOccurred` | Индивидуальное обращение | | **Events** | | | | | | | | Все сессионные мероприятия | | | | `on()`, `once()` | 40+ типов мероприятий | | | Стриминг | `streaming: true` | События Delta | | **Конфигурация сессии** | | | | | | | | Пользовательские агенты | | | | `customAgents` конфигурация | Определить специализированные агенты | | | Системное сообщение | | | | `systemMessage` конфигурация | Дополнение или замена | | | Настраиваемый поставщик | | | | `provider` конфигурация | Поддержка BYOK | | | Бесконечные сессии | | | | `infiniteSessions` конфигурация | Автоматическое сжатие | | | Обработчик разрешений | `onPermissionRequest` | Утверждение и отклонение запросов; При необходимости присоединение `decisionContext` телеметрии автоматического утверждения | | Обработчик пользовательского ввода | `onUserInputRequest` | Занимайся ask\_user | | Skills | | | | `skillDirectories` конфигурация | Настраиваемые навыки | | | Навыки инвалидов | | | | `disabledSkills` конфигурация | Отключите специфические навыки | | | Каталог конфигураций | | | | `configDir` конфигурация | Отменить местоположение конфигурации по умолчанию | | | имя клиента; | | | | `clientName` конфигурация | Идентифицировать приложение в User-Agent | | | Рабочий каталог | | | | `workingDirectory` конфигурация | Настройка cwd сеанса | | | Дополнительные каталоги | | | | `additionalDirectories` конфигурация | Предоставление доступа к сеансу за пределами рабочего каталога; повторное предоставление резюме | | | **экспериментальный** | | | | | | | | Управление агентами | `session.rpc.agent.*` | Списать, выбирать, снимать выбор, получить текущего агента | | Режим флота | `session.rpc.fleet.start()` | Параллельное выполнение субагентов; см. [Режим флота](/ru/copilot/how-tos/copilot-sdk/features/fleet-mode) | | Ручное уплотнение | `session.rpc.history.compact()` | Уплотнение по требованию триггера | | Очистка контекста | `session.rpc.history.clearContext()` | Замена контекста беседы из средства терминала | | Историческое сокращение | `session.rpc.history.truncate()` | Удалять события с точки и далее | | Сессионное форкование | `server.rpc.sessions.fork()` | Форк сессии в определённый исторический момент | ### ❌ Недоступно в SDK (только для CLI) | Функция | Команда/опция CLI | Reason | | ------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------- | | **Экспорт сессий** | | | | | | | | Экспорт в файл | | | | `--share`, `/share` | Не по протоколу | | | Экспорт в суть | | | | `--share-gist`, `/share gist` | Не по протоколу | | | **Интерактивный интерфейс** | | | | | | | | Команды слэш | | | | `/help`, , `/clear``/exit`и т. д. | Только для TUI | | | Диалог с выбором агента | `/agent` | Интерактивный интерфейс | | Диалог в режиме дифференциала | `/diff` | Интерактивный интерфейс | | Диалог обратной связи | `/feedback` | Интерактивный интерфейс | | Выбор тем | `/theme` | Интерфейс терминала | | Модель выбора | `/model` | Интерактивный интерфейс (используйте SDK `setModel()` ) | | Копировать в буфер обмена | `/copy` | Терминально-специфическая | | Управление контекстом | `/context` | Интерактивный интерфейс | | **Исследования и история** | | | | | | | | Глубокое исследование | `/research` | Рабочий процесс TUI с веб-поиском | | Инструменты истории сессий | `/chronicle` | Стендап, советы, улучшение, переиндексация | | **Возможности терминала** | | | | | | | | Цветовой выход | `--no-color` | Терминально-специфическая | | Режим экранного читателя | `--screen-reader` | Accessibility | | Рендеринг с богатыми дифференциальными элементами | `--plain-diff` | Терминальный рендеринг | | Стартап-баннер | `--banner` | Визуальный элемент | | Стримерный режим | `/streamer-mode` | Режим отбора TUI | | Альтернативный буфер экрана | | | | `--alt-screen`, `--no-alt-screen` | Терминальный рендеринг | | | Поддержка мыши | | | | `--mouse`, `--no-mouse` | Терминальный вход | | | **Ярлыки пути/разрешения** | | | | | | | | Разрешить все пути | `--allow-all-paths` | Используйте обработчик прав | | Разрешить все URL | `--allow-all-urls` | Используйте обработчик прав | | Разрешить все права | | | | `--yolo`, , `--allow-all``/allow-all` | Используйте обработчик прав | | | Разрешения гранулированных инструментов | | | | `--allow-tool`, `--deny-tool` | Используйте `onPreToolUse` крючок | | | Контроль доступа к URL | | | | `--allow-url`, `--deny-url` | Используйте обработчик прав | | | Инструменты, разрешённые для сброса, | `/reset-allowed-tools` | Командование TUI | | **Управление каталогами** | | | | | | | | Добавить каталог | | | | `/add-dir`, `--add-dir` | Настройка в сессии | | | Каталоги списков | `/list-dirs` | Командование TUI | | Смена каталога | `/cwd` | Командование TUI | | **Управление плагинами/MCP** | | | | | | | | Команды плагинов | `/plugin` | Интерактивное управление | | Управление сервером MCP | `/mcp` | Интерактивный интерфейс | | **Управление учетными записями** | | | | | | | | Поток входа | | | | `/login`, `copilot auth login` | Поток устройств OAuth | | | Выход | | | | `/logout`, `copilot auth logout` | Прямой CLI | | | Сведения о пользователе | `/user` | Командование TUI | | **Сессионная деятельность** | | | | | | | | Ясный разговор | `/clear` | Только для TUI | | Вид плана | `/plan` | Только для TUI (используйте SDK `session.rpc.plan.*` ) | | Управление сеансами | | | | `/session`, , `/resume``/rename` | Рабочий процесс TUI | | | Режим флота (интерактивный) | `/fleet` | Только для TUI (используйте SDK `session.rpc.fleet.start()` ) | | **Управление навыками** | | | | | | | | Управление навыками | `/skills` | Интерактивный интерфейс | | **Управление задачами** | | | | | | | | Просмотр фоновых задач | `/tasks` | Командование TUI | | **Использование и статистика** | | | | | | | | Использование токенов | `/usage` | Подписывайтесь на события использования | | **Проверка кода** | | | | | | | | Проверить изменения | `/review` | Командование TUI | | **Делегирование** | | | | | | | | Делегат в PR | `/delegate` | Рабочий процесс TUI | | **Настройка терминала** | | | | | | | | Интеграция оболочки | `/terminal-setup` | Специфичная для раковины | | **Развитие** | | | | | | | | Экспериментальный переключатель | | | | `/experimental`, `--experimental` | Флаг во время выполнения | | | Управление пользовательскими инструкциями | `--no-custom-instructions` | Флаг CLI | | Сеанс диагностики | `/diagnose` | Командование TUI | | Просмотр/управление инструкциями | `/instructions` | Командование TUI | | Сбор отладочных журналов | `/collect-debug-logs` | Средство диагностики | | Переиндекс рабочая область | `/reindex` | Командование TUI | | Интеграция с IDE | `/ide` | Рабочий процесс, специфичный для IDE, | | **Неинтерактивный режим** | | | | | | | | Режим подсказки | | | | `-p`, `--prompt` | Одноразовая казнь | | | Интерактивный запрос | | | | `-i`, `--interactive` | Автоматическое выполнение, затем интерактивное | | | Бесшумный выход | | | | `-s`, `--silent` | Удобно для сценария | | | Продолжить сессию | `--continue` | Резюме — последнее | | Выбор агента | `--agent ` | Флаг CLI | ## Обходные пути ### Режим флота Режим флота доступен `session.rpc.fleet.start()` для SDK-приложений, которые хотят, чтобы время выполнения отправляло параллельные субагенты для более крупных целей. Используйте его, когда независимые подзадачи могут выполняться одновременно и затем обобщаться основной сессией. Полное руководство смотрите [в статье AUTOTITLE](/ru/copilot/how-tos/copilot-sdk/features/fleet-mode). ### Экспорт сессий Эта `--share` опция недоступна через SDK. Обходные пути: 1. **Собирайте события вручную** — подписывайтесь на события сессии и создайте собственный экспорт: ```typescript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself ``` 2. **Используйте CLI напрямую для экспорта** — запускайте CLI `--share` для одноразового экспорта. ### Контроль разрешений SDK использует модель **отказов по умолчанию** . Все запросы на разрешения (запись файлов, команды shell, выборка URL и т.д.) отклоняются, если только ваше приложение не предоставляет обработчик `onPermissionRequest` . Вместо `--allow-all-paths` или `--yolo`, используйте обработчик разрешений: ```typescript const session = await client.createSession({ onPermissionRequest: approveAll, }); ``` ### Отслеживание использования токенов Вместо `/usage`, подписывайтесь на события использования: ```typescript session.on("assistant.usage", (event) => { console.log("Tokens used:", { input: event.data.inputTokens, output: event.data.outputTokens, }); }); ``` ### Уплотнение контекста Вместо `/compact`этого настройте автоматическое уплотнение или активируйте её вручную: ```typescript // Automatic compaction via config const session = await client.createSession({ infiniteSessions: { enabled: true, backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization }, }); // Manual compaction (experimental) const result = await session.rpc.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` > \[!NOTE] > Пороги — это коэффициенты использования контекста (0,0-1,0), а не абсолютное количество токенов. ### Управление планами Программно читайте и пишите планы сессий: ```typescript // Read the current plan const plan = await session.rpc.plan.read(); if (plan.exists) { console.log(plan.content); } // Update the plan await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" }); // Delete the plan await session.rpc.plan.delete(); ``` ### Управление сообщениями Введите сообщение в текущий ход LLM без прерывания: ```typescript // Steer the agent mid-turn await session.send({ prompt: "Focus on error handling first", mode: "immediate" }); // Default: enqueue for next turn await session.send({ prompt: "Next, add tests" }); ``` ## Ограничения протокола SDK может получать доступ только к функциям, открытым через протокол JSON-RPC CLI. Если вам нужна функция CLI, которая недоступна: 1. **Проверьте альтернативы** — многие функции имеют аналоги SDK (см. обходные решения выше) 2. **Используйте CLI напрямую** — для разовых операций вызовите CLI 3. **Запросить функцию** — Откройте проблему, чтобы запросить поддержку протокола ## Совместимость версий | Диапазон протокола SDK | Версия протокола CLI | Compatibility | | ---------------------- | -------------------- | -------------------------------------------- | | v2–v3 | версия 3 | Полная поддержка | | v2–v3 | версия 2 | Поддерживается автоматическими адаптерами v2 | SDK согласует версии протокола с CLI при запуске. SDK поддерживает версии протокола 2–3. При подключении к серверу CLI v2 SDK автоматически адаптируется `tool.call` и `permission.request` сообщает к модели событий v3 — без изменений кода. Проверьте версии во время выполнения: ```typescript const status = await client.getStatus(); console.log("Protocol version:", status.protocolVersion); ``` ## См. также * [Создайте своё первое приложение на базе Copilot](/ru/copilot/how-tos/copilot-sdk/getting-started) * [Сессионные хуки](/ru/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Использование MCP-серверов с SDK GitHub Copilot](/ru/copilot/how-tos/copilot-sdk/features/mcp) * [Руководство по отладке](/ru/copilot/how-tos/copilot-sdk/troubleshooting/debugging)