---
doc_id: REF-CK8S-0012
type: provider-integration
title: "kodex — модель интеграции с провайдерами в третьей волне"
status: active
owner_role: SA
created_at: 2026-04-21
updated_at: 2026-04-23
related_issues: [376, 470]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave3"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Модель интеграции с провайдерами в третьей волне

## TL;DR
- Ядро платформы не завязывается на GitHub-специфику; все операции идут через provider-интерфейсы, где GitHub — первая реализация, GitLab — следующая.
- Slot-агент создаёт и обновляет `Issue/PR` обычным рабочим способом: через `gh` или нативный API провайдера от имени настроенного аккаунта.
- Быстрый agent-manager работает с платформой через платформенный MCP-сервер и через него инициирует разрешённые provider-операции.
- `provider-hub` отвечает за нормализацию webhook-событий, зеркала, ограничения провайдеров, машинные аккаунты и внешние операции платформы.
- Платформа использует provider-native поля там, где это даёт устойчивую пользу для истории и навигации, но не пытается хранить в них быстро меняющееся runtime-состояние.
- Лимиты, необходимость переавторизации и отказ внешней системы должны становиться явной частью состояния ожидания и уведомлений, а не теряться внутри сессии агента.
- Provider-контур теперь должен обслуживать не только кодовые репозитории и рабочие артефакты, но и репозитории-источники пакетов, репозитории проектной документации, release branches/tags и будущие адаптеры платёжных провайдеров.

## 1. Цель этой волны
Эта волна фиксирует общий контракт работы платформы с внешними провайдерами.

Под провайдерами здесь понимаются:
- поставщики репозиториев и рабочих артефактов (`GitHub`, в следующей реализации `GitLab`);
- поставщики репозиториев-источников пакетов для plugins и guidance packages;
- поставщики репозиториев проектной документации;
- поставщики моделей и runtime-доступа, если их лимиты и авторизация влияют на запуск агентов;
- поставщики платежей и коммерческих операций, когда они войдут в платформенный billing contour;
- другие внешние системы, где платформа не хранит истину сама, а работает через адаптер.

В рамках этой волны главным приоритетом остаётся модель поставщика репозиториев и рабочих артефактов. Остальные провайдеры должны подчиняться тем же общим принципам:
- одна расширяемая интерфейсная граница;
- явная нормализация;
- явная модель лимитов и блокировок;
- отсутствие вендорной логики в ядре.

Это означает, что каталог пакетов, billing и автоматизация релизов не получают свои особые обходные интеграционные контуры. Они используют ту же provider-грань с профильной нормализацией.

## 2. Каноническая граница провайдера

### 2.1. Что должен уметь provider-контур
Provider-контур обязан уметь:
- принять входящее событие от провайдера;
- нормализовать его в платформенную форму;
- получить каноническое чтение по нужному внешнему объекту;
- создать или обновить provider-native артефакт;
- записать результат внешней операции и ограничения;
- сообщить о лимите, блокировке или необходимости переавторизации.

### 2.2. Что не должно просачиваться в ядро
В ядро не должны просачиваться:
- конкретные REST/GraphQL пути GitHub;
- GitHub-специфичные наименования и сущности, если они не имеют общего провайдерного смысла;
- логика выбора между `gh` и HTTP API как часть доменной модели;
- особенности конкретного review payload, если они не прошли нормализацию.

## 3. Категории provider-операций

### 3.1. Входящие сигналы
Платформа должна принимать:
- webhook-события;
- mention-комментарии;
- изменения `Issue/PR/MR`;
- review-события;
- служебные callbacks от внешних систем.

### 3.2. Каноническое чтение у провайдера
Нужен для сценариев, где mirror недостаточен:
- перед принятием важного перехода;
- перед выполнением чувствительного или рискованного действия;
- при споре между локальной проекцией и внешним состоянием;
- при восстановлении после сбоя синхронизации.

### 3.3. Изменяющие действия
Платформа и агент должны уметь выполнять:
- создание `Issue`;
- обновление `Issue`;
- создание `PR/MR`;
- публикацию комментариев;
- установку labels и relationships;
- работу с assignees, milestone и project fields, если они входят в policy проекта.

### 3.4. Package source и release branch операции
Новая модель должна покрывать и другие provider-native действия:
- чтение репозиториев-источников пакетов;
- получение manifest, версий и метаданных пакета;
- чтение и изменение репозиториев проектной документации в рамках разрешённых задач;
- создание связанного набора `PR/MR` в нескольких репозиториях по одной задаче;
- создание и сопровождение provider-native release branches и tags;
- операции чтения по release-related provider state без создания внутреннего дубликата ветки.

## 4. Агентный и платформенный контур работы с провайдером

### 4.1. Что делает быстрый agent-manager
Agent-manager работает с платформой через платформенный MCP-сервер.

Это значит:
- актуальные данные он получает не прямыми вызовами в GitHub/GitLab и не из локальных ad-hoc клиентов;
- разрешённые provider-операции он инициирует через платформенный инструментальный контур;
- вся быстрая orchestration-логика опирается на owner-сервисы и их MCP-инструменты.

### 4.2. Что делает slot-агент
Slot-агент работает с provider-native артефактами как обычный исполнитель:
- создаёт и обновляет `Issue/PR`;
- пишет комментарии;
- ставит разрешённые labels и связи.

Базовый путь определяется профилем роли, образом slot и доступными секретами.

Допустимые варианты:
- `gh` внутри slot, если это GitHub;
- `glab` или иной штатный CLI-клиент провайдера, если это соответствует выбранной интеграции;
- нативный API провайдера, если CLI не подходит или role policy требует именно API-вызовов.

Для slot-агента это не MCP-операция и не специальный скрытый платформенный путь. Это обычный рабочий контур.

Объём provider-операций при этом определяется профилем роли.
Сам факт запуска конкретной роли на конкретном этапе при этом задаётся не профилем роли, а `stage role binding` внутри flow.

Например:
- основная роль этапа может создавать `PR` и follow-up `Issue`;
- проверяющая роль может только комментировать и ставить аппрув по существующему `PR`;
- контрольная роль может проверять тело артефакта и комментарии на policy-нарушения без создания нового артефакта.
- роль self-improve может создать `PR` не в кодовом репозитории, а в репозитории руководящего пакета;
- роль разработки может создать несколько `PR/MR` в разных репозиториях проекта, если `services.yaml` и policy разрешают такой состав работы.

### 4.3. Что делает платформа
Платформа через `provider-hub` делает то, что не должно быть размазано по агентам:
- принимает webhook-события;
- поддерживает зеркала и cursors;
- проверяет лимиты;
- ведёт машинные аккаунты;
- фиксирует внешний результат и ошибки;
- выдаёт каноническое чтение другим сервисам-владельцам.

## 5. Provider-native поля, на которые опирается платформа

### 5.1. Базовый канонический набор
В первой реализационной линии платформа должна опираться на:
- тип задачи;
- labels;
- relationships;
- комментарии и mentions;
- состояние открытия/закрытия;
- review state;
- связанный `PR/MR`;
- assignees;
- milestone и project fields, если проект реально их использует.

Если конкретный провайдер не даёт один и тот же первичный набор полей, `provider-hub` обязан отобразить этот смысл в поддерживаемую комбинацию provider-native полей без перелома общей модели платформы.

### 5.2. Принцип выбора полей
Провайдерное поле допустимо использовать, если оно:
- нативно поддерживается системой;
- понятно человеку без знания внутренностей `kodex`;
- полезно для истории, навигации и ручной работы;
- не требует платформе постоянно переписывать быстро меняющееся состояние.

### 5.3. Что не надо пытаться впихнуть в provider-native поля
В provider-native поля не надо помещать:
- текущее runtime-состояние slot;
- внутренние статусы `job`;
- счетчики технических ретраев;
- быстро меняющиеся диагностические детали;
- внутренние системные идентификаторы, нужные только платформе.

Такие данные должны жить в платформе и попадать в provider только в виде осмысленного открытого текста, если это действительно нужно человеку.

### 5.4. Provider-native branches и tags
Для wave 5.1 фиксируется отдельное правило:
- provider остаётся владельцем веток и тегов;
- платформа поверх них хранит только release policy, release line и rollout state;
- branch rules и автоматизация релизов не должны создавать внутренний клон Git как доменную модель платформы.

## 6. Машинные аккаунты и выбор аккаунта

### 6.1. Почему нужен явный аккаунтный контур
Новая модель должна допускать:
- несколько бот-аккаунтов в GitHub/GitLab;
- несколько учётных записей поставщиков моделей и runtime-доступа;
- разные конфигурации по ролям агентов, проектам или репозиториям.

### 6.2. Что должен уметь `provider-hub`
`provider-hub` должен уметь:
- хранить машинные аккаунты и их статус;
- различать платформенные и агентные аккаунты;
- понимать область действия аккаунта;
- выбирать аккаунт по project/repository/role policy;
- фиксировать, какой аккаунт выполнил внешнюю операцию;
- сообщать, если аккаунт упёрся в лимит, отозван или требует переавторизации.

Это важно и для пользовательских ролей:
- одна роль может работать от машинного аккаунта бота;
- другая роль может использовать отдельный account class;
- параллельные проверяющие и контрольные роли не должны случайно получать лишние внешние права.

### 6.3. Переавторизация и блокировки
Если внешний провайдер требует переавторизацию или сообщает о проблеме с доступом:
- это не прячется в лог агента;
- `provider-hub` формирует явное ограничение;
- `agent-manager` переводит run в состояние ожидания;
- `interaction-hub` создаёт запрос к человеку и уведомление.

Это относится и к поставщикам репозиториев, и к поставщикам моделей или runtime-доступа, если они участвуют в запуске агента.

## 7. Rate limits и другие внешние ограничения

### 7.1. Общий принцип
Лимиты внешней системы должны быть видимы платформе как отдельное первичное ограничение.

Нельзя считать нормой ситуацию, когда:
- агент молча подождал;
- ошибка ушла только в лог;
- оператор не понимает, почему работа стоит.

### 7.2. Что должна уметь модель
Модель должна поддерживать:
- текущий известный статус лимита;
- время следующей допустимой попытки, если оно доступно;
- классификацию ограничения;
- связь ограничения с run, `job`, аккаунтом и проектом;
- уведомление и операторскую видимость.

### 7.3. Типовые классы ограничений
Минимально нужно различать:
- rate limit;
- квота модели или провайдера;
- необходимость ручной авторизации;
- временная недоступность внешней системы;
- отказ по правам доступа.

## 8. Webhook, polling и контуры восстановления синхронизации

### 8.1. Webhook — основной вход
Основной входящий путь остаётся webhook-driven.

### 8.2. Но webhook не может быть единственным способом синхронизации
Нужны контуры восстановления для ситуаций:
- webhook потерян;
- webhook пришёл частично;
- локальный mirror повреждён или устарел;
- перед критической контрольной точкой нужен повторный канонический запрос к провайдеру.

Канонический подход к восстановлению:
- основной поток идёт через webhook;
- `provider-hub` умеет точечно перечитывать объект и его связи;
- фоновая досинхронизация запускается только для проблемных объектов;
- ручное выравнивание конкретной сущности и её связей остаётся допустимым действием Owner или оператора;
- вся досинхронизация работает с учётом rate limit и policy выбора аккаунта.

### 8.3. Роль `worker`
`worker` может исполнять задачи синхронизации и восстановления, но:
- не становится владельцем provider state;
- действует по поручению `provider-hub`;
- не принимает доменных решений о flow или acceptance.

## 9. Что платформа считает нормализованным состоянием провайдера
Нормализованное состояние провайдера должно позволять платформе одинаково думать о:
- `Issue`;
- `PR/MR`;
- комментарии;
- mention;
- relationship;
- review-сигнале;
- ограничении внешнего API.

При этом нормализованная модель не должна быть обрезанной до потери смысла. Она обязана сохранять:
- ссылку на исходный внешний объект;
- нужные provider-native поля;
- сведения о последней синхронизации;
- признак, нужен ли повторный канонический запрос.

## 10. GitHub first, GitLab next

### 10.1. Что считается первой реализацией
Первой полноценной реализацией считается GitHub:
- webhook;
- `Issue/PR/comments/mentions`;
- bot-операции;
- rate limit handling;
- review и relationships.

### 10.2. Что должно быть готово сразу
Сразу должны быть готовы:
- provider-интерфейсы;
- нормализованная модель;
- отсутствие GitHub-специфичных допущений в ядре;
- место для второй реализации под GitLab.

### 10.3. Чего не нужно делать в этой волне
В этой волне не нужно:
- реализовывать GitLab;
- заранее проектировать десятки провайдеров;
- выбирать окончательную модель расширения внешних каналов обратной связи.

Но архитектурная граница под них уже должна существовать.
