---
doc_id: PMD-CK8S-PLATFORM-0001
type: product-model
title: kodex — сквозная продуктовая модель платформы
status: active
owner_role: PM
created_at: 2026-04-26
updated_at: 2026-05-07
related_issues: [599, 600, 601, 602, 655]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-product-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# Продуктовая модель kodex

## TL;DR

`kodex` — платформа управления агентной разработкой поверх нативных сущностей провайдера и Kubernetes-runtime. Платформа не заменяет GitHub/GitLab, а добавляет управляемую оркестрацию, runtime, политики, приёмку, аудит, уведомления, пакетную модель, организации и операторские интерфейсы.

## Главный принцип

Если сущностью удобно управлять в GitHub/GitLab, она остаётся у провайдера. Если сущность нужна для оркестрации, безопасности, runtime, аудита, приёмки или биллинга, она принадлежит платформе.

Из этого следует:
- `Issue` является базовой рабочей задачей;
- инициатива является `Issue` типа `initiative`;
- `PR/MR` остаётся артефактом изменения у провайдера;
- review остаётся у провайдера;
- платформа хранит зеркальные проекции, состояние дозаполнения, платформенные метаданные, связи, ожидания приёмки и операторские представления;
- платформа не создаёт внутренние заменители `Issue`, `PR/MR`, веток, тегов и образов.

## Участники

| Участник | Назначение |
|---|---|
| Пользователь платформы | Управляет задачами, проектами, решениями и взаимодействием с agent-manager. |
| Owner | Утверждает документы, high-risk переходы, релизные решения и другие контрольные точки по policy. |
| Оператор платформы | Следит за `run`, `job`, slot, кластерами, сбоями и уведомлениями. |
| Agent-manager | Быстрый агент управления, который разбирает запрос, выбирает flow/роль, инициирует операции и общается с пользователем. |
| Ролевой агент | Агент, выполняющий этап, проверку, контрольную роль или операционное действие в разрешённом контуре. |
| Acceptance machine | Машинный контур проверки артефактов, обязательных полей, watermark, policy и переходов. |

## Управленческие сущности платформы

| Сущность | Краткий смысл |
|---|---|
| Организация | Контур владения, пользователей, групп, проектов, биллинга и инфраструктурных ограничений. |
| Группа пользователей | Способ назначать права, подписки и правила не одному пользователю, а группе. |
| Проект | Контейнер настроек, репозиториев, flow, политик, внешних аккаунтов и runtime-ограничений. |
| Репозиторий | Привязанный источник кода, проектной документации, конфигурации или пакета. |
| Внешний аккаунт | Учётная запись GitHub/GitLab, провайдера моделей, канала связи или другой внешней системы. |
| Пакет | Версионируемый репозиторий-источник, который поставляет плагин, руководящую документацию или другой расширяемый контур. |
| Каталог пакетов | Локальный каталог установленных и доступных пакетов конкретной установки платформы. |
| Сервер | Инфраструктурный узел размещения или управляемый вычислительный узел. |
| Kubernetes-кластер | Runtime-контур для платформы, slots, плагинов и проектных workloads. |
| Placement policy | Правила выбора допустимого сервера или кластера для организации, проекта, репозитория, пакета или workload. |
| Billing account | Коммерческий контур организации или проекта для учёта затрат и расчётов. |
| Cost record | Запись затрат по compute, storage, runtime, внешним провайдерам или пакетам. |
| Release policy | Правила ветвления, gates, evidence и выкладки. |
| Release line | Координационный объект поставки, связывающий provider-native ветки, теги, задачи, `PR/MR`, `job` и release decisions. |
| Automation rule | Правило запуска по расписанию, событию или внешнему сигналу. |

## Рабочие сущности провайдера

| Сущность | Как используется платформой |
|---|---|
| `Issue` | Базовая задача: инициатива, этапная задача, follow-up, риск, инцидент, self-improve. |
| `PR/MR` | Изменение кода, документации, конфигурации или отчётного артефакта. |
| Комментарий | Обратная связь, structured feedback, mention, запрос уточнения или результат проверки. |
| Mention | Нативный запуск взаимодействия с agent-manager или ролевым агентом. |
| Relationship | Связь между задачами, `PR/MR`, этапами, блокировками, рисками и follow-up. |
| Ветка и тег | Provider-native объекты, которые платформа связывает с release policy и release line. |

## Данные платформы по нативным сущностям

Платформа не создаёт внутренний заменитель `Issue` или `PR/MR`, но хранит данные, без которых невозможны быстрый UI, приёмка, уведомления, поиск и защита от лимитов провайдера.

| Класс данных | Что хранится | Кто источник истины |
|---|---|---|
| Идентификатор провайдера | provider, owner, repo, номер, `node_id` или аналог, URL | Провайдер |
| Зеркальная проекция | Заголовок, состояние, labels, assignees, milestone, project fields, связи, digest, время синхронизации и данные для клиентских экранов без полного тела и diff | Провайдер |
| Распознанный контракт | Watermark, обязательные разделы, открытые инструкции, тип задачи, ожидаемые `PR/MR` и follow-up | Провайдер плюс правила платформы |
| Платформенные метаданные | Состояние приёмки, риск, policy decisions, связи с `run`, `job`, slot, сессиями, уведомлениями и операторскими списками | Платформа |
| Синхронизация | Webhook offsets, reconciliation checkpoints, ошибки дозаполнения и признаки рассинхронизации | Платформа |

Если `Issue` или `PR/MR` создан напрямую в GitHub/GitLab, платформа принимает событие webhook или находит артефакт reconciliation-задачей, создаёт проекцию, проверяет обязательные признаки и запускает дозаполнение через agent-manager, если policy разрешает исправлять артефакт автоматически.

### Модель синхронизации проекций

| Слой | Назначение | Что хранится |
|---|---|---|
| Webhook inbox | Быстро принять событие провайдера и не потерять его до бизнес-обработки. | Сырой payload, идентификатор доставки, provider, repo, тип события, received_at, статус, счётчик повторов. |
| Incremental reconciliation | Найти изменения, если webhook не пришёл, пришёл с задержкой или обработался с ошибкой. | `sync_cursor`, окно перекрытия, `last_success_at`, `last_checked_at`, `last_error`, `rate_budget_state`. |
| Приоритеты синхронизации | Не тратить лимиты провайдера на холодные архивные данные. | Класс hot/warm/cold, `next_check_at`, политика повторов, причина. |
| Контроль рассинхронизации | Понять, что локальная проекция может устареть. | `source_updated_at`, `source_digest`, `last_verified_at`, `drift_status`, причина рассинхронизации. |

Горячими считаются сущности, которые участвуют в активном flow, открытом `PR/MR`, Human gate, release line, running `run`, ожидаемой приёмке или свежем обсуждении. Такие сущности получают более частые проверки и приоритет при дефиците лимитов провайдера.

Если slot-агент создаёт или меняет артефакт через `gh`, он должен передать платформе идентификатор провайдера как ускоряющий сигнал на обновление. Источником истины всё равно остаётся провайдер: платформа после сигнала перечитывает артефакт через адаптер провайдера или ждёт webhook/reconciliation.

### Учёт лимитов `gh`

`gh` подходит для прямой работы slot-агента с provider-native артефактами, но не является полноценным платформенным счётчиком расхода лимитов.

Принятая модель:
- `gh api rate_limit` используется для снимка состояния лимитов до и после agent-run;
- `gh api --include` может дать заголовки ответа для операций, которые агент выполняет через `gh api`;
- обычные высокоуровневые команды `gh issue`, `gh pr` и похожие команды не считаются достаточным источником полной телеметрии лимитов;
- строгий учёт и принудительное соблюдение лимитного бюджета должны идти через будущий provider proxy или MCP-ручки платформы.

## Процессы, роли и промпты

| Понятие | Правило |
|---|---|
| `Flow` | Шаблон процесса выполнения работы: этапы, переходы, артефакты, роли, gates и automation. |
| Этап | Один шаг flow, например `intake`, `prd`, `dev`, `qa`, `release` или `postdeploy`. |
| Профиль роли | Описание роли агента, её назначения, runtime, MCP-прав, аккаунтов и допустимого участия в flow. |
| Привязка роли к этапу | Правило, которое говорит, как роль участвует в конкретном этапе: исполнитель, проверка, `gatekeeper` или вспомогательная роль. |
| Шаблон промпта | Версионируемый текст `work` или `revise`, хранящийся в БД и связанный с ролью. |
| Установочная фикстура | Seed-файл в репозитории платформы для первичной загрузки встроенных flow, ролей и шаблонов. |

Каноническое runtime-состояние `flow`, ролей и шаблонов находится в БД платформы. Репозиторий платформы хранит только установочные фикстуры. UI редактирует эти объекты через версии, аудит, diff и policy-проверку.

## Рабочая модель

1. Пользователь создаёт запрос через командный центр, голос, подключённый пакет внешнего канала, `Issue`, комментарий или mention.
2. Agent-manager определяет намерение, проектный контекст, допустимые flow, роли и ограничения.
3. Если нужен управляемый процесс, создаётся или используется `Issue` нужного типа.
4. Ролевой агент получает workspace: кодовые репозитории, проектную документацию, зависимые источники и руководящие пакеты.
5. Агент оформляет provider-native артефакты через `gh` или API провайдера, а платформенные операции выполняет через MCP.
6. Acceptance machine проверяет открытые разделы, watermark, provider-native поля, связи, policy и ожидаемый набор `PR/MR`.
7. Если flow требует следующий этап, агент создаёт follow-up `Issue` нужного типа.
8. Если policy требует Human gate или дополнительные роли проверки, agent-manager запускает их до перехода.

## Runtime и технические операции

| Понятие | Что означает |
|---|---|
| Агентная сессия | Логический контекст работы агента, который можно продолжить. |
| `Run` | Один исполняемый запуск агента внутри сессии. |
| `Slot` | Изолированное Kubernetes-окружение под работу. |
| `Job` | Техническая операция платформы: зеркалирование зависимостей, сборка, публикация образа, deploy, cleanup, health-check или housekeeping. |

`Run` и `job` нельзя смешивать. `Run` отвечает за агентную работу, `job` отвечает за техническое выполнение среды и поставки.

По `job` платформа хранит статус, timestamps, связанный контекст, причину ошибки, короткий хвост лога и ссылку на полный источник логов. Полные технические логи не становятся обязательной моделью PostgreSQL.

## Документация и знания

Платформа различает три класса документов:

| Класс | Где живёт | Как используется |
|---|---|---|
| Платформенная документация | `docs/platform/**`, `docs/domains/**`, `docs/catalogs/**`, `docs/delivery/**` | Каноника самой платформы. |
| Руководящая документация | Source submodule или package repository | Правила для агентов, шаблоны и инженерные гайды. |
| Проектная документация | Репозитории проекта, описанные в `services.yaml` | Документация продукта, сервисов, архитектуры и эксплуатации конкретного проекта. |

Агент в slot должен работать с локально доступными источниками. В первой версии vector storage не является обязательным механизмом доступа к знаниям.

## Минимальный объём первой версии

| Направление | Минимум первой версии |
|---|---|
| Доступ | Owner-организация, клиентские организации, пользователи, группы, allowlist, внешние аккаунты и вычисление прав. |
| Проекты | Проекты, репозитории, источники документации, release policy и workspace composition. |
| Рабочие артефакты | `Issue`, `PR/MR`, комментарии, mentions, relationships, watermark и acceptance. |
| Пакеты | Установленные пакеты, пользовательские источники, guidance packages, plugin packages и клиент к магазину пакетов. |
| Агентная работа | Agent-manager, flow, роли, шаблоны промптов, sessions, runs и acceptance. |
| Runtime и fleet | Slot, job, workspace materialization, cleanup/prewarm/reuse, управление серверами и Kubernetes-кластерами, health-check и мониторинг с первым режимом один production-кластер. |
| Взаимодействие | UI, голос, уведомления, Human gate и внешние каналы через пакеты и общий контракт взаимодействия. |
| Биллинг | Учёт затрат и основа для выставления счетов. |
| Релизы | Release policy, release line, gates, deploy jobs и postdeploy-контур. |

## Что уточняется дальше

- Сквозной архитектурный каркас и границы сервисов.
- Домен доступа, организации, группы, SSO и внешние аккаунты.
- Delivery, трассируемость, приёмка и карты связей документов с работами.
- Ops, управление серверами и кластерами, deploy gate и наблюдаемость.
