GigaChat изнутри

Сверено с выпуском 0.36.0, 14.11.2026.

Статус: реализовано (Pulse 0.15.4+). Документ изначально писался до появления встроенного ApiAgentSession (агент «Локальная модель»), поэтому вместо отдельного цикла агента GigaChat переиспользует его — см. «Архитектура» ниже.

GigaChat в Pulse теперь две разные вещи, и путать их не стоит:

  • агент — ведёт задачу, правит файлы, запускает команды (весь документ, кроме одноимённого раздела ниже);
  • провайдер AI-действий — пишет сообщение коммита, имя stash, объяснение изменений и тексты PR (раздел «GigaChat как провайдер AI-действий»).

Ключ авторизации у них один — тот, что задан на карточке агента.

Цель: подключить GigaChat (Сбер) по ключу авторизации как ещё одного агента — рядом с Claude Code, Kimi Code и Codex. У GigaChat нет ACP-адаптера и CLI с агентным циклом, поэтому агент встроенный: main-процесс сам ведёт цикл «модель → вызов инструмента → результат → модель» поверх HTTP API и превращает его в те же SessionEvent, что и ACP-адаптеры. Для renderer разницы нет.

API (что известно)

Что Как
Авторизация POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth, заголовки Authorization: Basic <ключ>, RqUID: <uuid>, тело scope=GIGACHAT_API_PERS (или _B2B / _CORP) → access_token на 30 минут; обновляем за 3 мин до истечения (expires_at, нормализуем секунды → ms)
Модели GET https://gigachat.devices.sberbank.ru/api/v1/models → список (GigaChat-2, GigaChat-2-Pro, GigaChat-2-Max, …) — это и есть config option «model»
Диалог POST /api/v1/chat/completions с messages, functions (JSON-схемы инструментов), function_call: "auto", stream: true (SSE)
Вызов функции ответ с finish_reason: "function_call" и delta.function_call {name, arguments} (целиком одним чанком, id нет); результат возвращается сообщением role: "function" со связью по имени
TLS цепочка сертификатов НУЦ Минцифры; PEM корня лежит в resources/certs/russian_trusted_root_ca.pem (extraResources → <Resources>/certs/), подключается через https.Agent({ ca }). rejectUnauthorized: false не используем. Транспорт — node:https (пакет undici — транзитивная зависимость, в сборку не попадает)

Ключ — секрет: хранить в userData/secrets.json с правами 0600 (значения зашифрованы safeStorage), никогда не писать в транскрипт, логи и agent-config.json; в UI только «задан / не задан» и хвост. access_token в логи не пишется (и так маскируется net.redactForLog по ключам authorization/access_token).

Архитектура (как реализовано)

src/main/agents/
  apiAgentSession.ts     общий цикл «запрос → вызовы инструментов → результаты → запрос»:
                         flavor 'openai' | 'gigachat', hooks getAuthToken/fetchImpl
  apiAgentStream.ts      SSE-разбор: content, tool_calls (openai), function_call (gigachat), usage
  apiAgentTools.ts       инструменты read_file/write_file/edit_file/list_dir/search/bash (общие)
  gigachat/
    client.ts            OAuth с кэшем токена (−3 мин до expires_at), models(),
                         createGigaChatFetch() — https.Agent с CA НУЦ
  registry.ts            gigachat: available = ключ задан; checkGigaChat() — кнопка «Проверить»
  • Интеграция с ApiAgentSession — без прослойки-клиента чата: сессия получает flavor: 'gigachat', fetchImpl: client.fetch (CA) и getAuthToken: () => client.getToken() (токен спрашивается перед каждым запросом, кэш внутри клиента). Различия формата инкапсулированы в сессии и apiAgentStream:
    • запрос: functions (= TOOL_SPECS.map(t => t.function) без обёртки type) + function_call: 'auto' вместо tools; stream_options не шлём (не поддерживается);
    • стрим: delta.function_call копится в apiAgentStream наравне с tool_calls;
    • история: assistant { content, function_call { name, arguments } } → { role: 'function', name, content } вместо tool_calls + role: 'tool'.
  • Инструменты, разрешения (режим и доверие сессии: «Спросить · План · Агент» и «Спрашивать · Правки сами · Полный доступ» с матрицей типов действий), лимит 30 кругов, отмена через AbortController, события message/tool_call/tool_call_update/usage/compaction/ turn_complete — общие с «Локальной моделью». Под границей чтения агента файловые инструменты закрыты, работа идёт через bash в песочнице.
  • Config options: model (из /models после «Проверить» или старта сессии; до этого — fallback GigaChat-2 / Pro / Max) — тот же чип композера; режим сессии — общие для всех агентов оси Pulse (см. Агенты и модели).
  • Usage: usage.{prompt_tokens,completion_tokens} из финального SSE-чанка → событие usage (окно по умолчанию 32k, как у локальной модели). Цены хода GigaChat не отдаёт: в истории сессий стоимость — «нет цены», денежный лимит на нём не срабатывает (см. Лимиты).
  • Scope из настроек карточки (GIGACHAT_API_PERS/_B2B/_CORP, мусор → PERS) уходит в OAuth.

Настройки

Настройки → Модели → карточка GigaChat (раньше была в «Агентах»; тексты ошибок и кнопка на странице «AI-функции» пока называют и открывают «Агенты»): поле «Ключ авторизации» (пароль), выбор scope, кнопка «Проверить» (IPC pulse:check-gigachat: OAuth + /models, показывает модели и срок токена, модели кэшируются в agent-config.json как config option). Агент available: true, когда ключ задан и агент включён.

GigaChat как провайдер AI-действий

AI-движок Pulse — это тексты, которые пишет не агент, а приложение по вашей кнопке: сообщение коммита, имя stash, объяснение изменений, заголовок и тело PR; через тот же движок идут план атомарных коммитов и AI-разрешение конфликтов. Провайдеров для них было четыре — CLI-агент, Anthropic, OpenAI и любой OpenAI-совместимый сервер; теперь в списке Настройки → AI-функции есть пятый, GigaChat (Сбер), сразу за CLI-агентом.

Ключ второй раз не вводится. Ключ авторизации Сбера один на приложение, лежит в secrets.json под gigachatAuthKey и задаётся на карточке агента. Поэтому у провайдера needsApiKey: false, а правду про доступ отдаёт отдельный метод hasCredentials — иначе страница AI показала бы второе поле ключа, которое никто не читает. На месте поля стоит строка «Ключ авторизации»: значок «ключ задан / не задан», кнопка перехода на карточку агента и кнопка «Проверить».

«Проверить» — настоящий обмен ключа на токен, мимо живого клиента (fresh). Ответ «работает» из кэша означал бы только «у нас ещё есть токен», а токен живёт полчаса: за это время ключ могли отозвать, и Pulse объявил бы рабочим то, чего не знает.

Тип доступа (scope) и список моделей берутся оттуда же, откуда их берёт агент: scope — из карточки, модели — из её кэша после «Проверить», а до первой проверки — известный набор GigaChat-2 / Pro / Max. Подобранный клиентом scope запоминается в карточке.

Один клиент на время работы приложения. Провайдер собирается заново на каждое действие (AIService.providerFor), поэтому транспорт живёт отдельно (cacheGigaChatTransport): без этого каждое сообщение коммита заново меняло бы ключ на токен по OAuth, заново читало с диска PEM корня НУЦ Минцифры и поднимало новый https.Agent, а трёхминутный кэш токена внутри клиента не срабатывал бы ни разу. Клиент переживает вызовы, пока не сменились ключ и scope.

Отказы названы по-разному, потому что лечатся по-разному:

Что пришло Что говорит Pulse
OAuth 401/403, «не подходит ни к одному типу доступа» ключ отклонён — и сразу адрес: «Настройки → Модели → карточка GigaChat»
OAuth не дозвонился сеть недоступна (менять рабочий ключ из-за обрыва связи человек не должен)
chat/completions 402 у аккаунта нет доступных токенов для этой модели — пополнить пакет или выбрать модель из тарифа
404 модель аккаунту недоступна
429 слишком много запросов, повторите через минуту
пустой ответ так и сказано; за текст не выдаётся

Адрес карточки в тексте ошибки обязателен: окно (renderer/src/ai.ts) показывает слова провайдера, только если он сам назвал раздел настроек. Без адреса человек получил бы общий совет «проверьте ключ в Настройки → AI-функции», где у GigaChat поля ключа нет вовсе.

Границы

  • Расшифровки речи через GigaChat нет. Микрофон в композере работает через провайдера AI, и у GigaChat эта дорога не сделана: кнопка не исчезает и ничего не обещает — в подсказке написано, что Pulse не расшифровывает речь через GigaChat, и предложен выход (OpenAI или свой сервер).
  • Потоковой выдачи у AI-действий нет ни у одного провайдера. Ответ ждут целиком, stream: false; у агента GigaChat поток есть, здесь его нет.
  • Остаток пакета токенов в AI-действиях не показывается. Клиент умеет спрашивать /balance, и у агента остаток виден — чипом «лимит» в чате после каждого хода и в ответе кнопки «Проверить» на карточке. AI-действия его не запрашивают: про исчерпанный пакет там говорит только отказ 402, то есть задним числом.
  • На живом ключе Сбера эта дорога не проверялась. Все проверки — на фейковом сервере; живой прогон (OAuth, /chat/completions, ответ модели) остаётся ручным.

Тесты

  • ai/providers/gigachat.test.ts — провайдер AI-действий: форма запроса, модель по умолчанию из карточки, отказ без ключа и без моделей с адресом карточки, разбор 401 / 402 / 500, отмена во время OAuth, отсутствие PEM корня, verifyKey как настоящий OAuth, один клиент на два действия подряд, «Проверить» мимо кэша, смена ключа.
  • renderer/src/aiErrors.test.ts — куда ведёт совет: слова провайдера с адресом раздела важнее общего текста про «Настройки → AI-функции».
  • gigachat/client.test.ts — OAuth-кэш (без сети до истечения, обновление за 3 мин, секунды→ms, один in-flight на параллельные вызовы), форма OAuth-запроса, models(), /balance.
  • apiAgentStream.test.ts — splitSse, tool_calls по индексу, function_call целиком и фрагментами, usage.
  • apiAgentSession.test.ts — полный цикл обоих flavor на фейковом сервере: формат запроса (functions vs tools), история (function vs tool), события, пермиссия.
  • registry.test.ts — available при ключе / без, модели из кэша, scope.

Живой прогон к API ключом владельца — вручную (кнопка «Проверить», затем задача с агентом GigaChat).