diff --git a/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md b/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md index 2563ca9a..0176affd 100644 --- a/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md +++ b/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md @@ -29,15 +29,15 @@ updateAddIfMissing: ### Спецификация запроса -Незаданные поля `templateId`, `templatePackSource`, `targetRepositoryUrl` и `targetBranch` заполняются из параметров сущности микросервиса по ролям [правил маппинга](../../home/mapping/#микросервисы). +Незаданные `templateId` и `templatePackSource` заполняются из управляемых параметров сущности микросервиса. Поля `targetRepositoryUrl` и `targetBranch` заполняются по ролям [правил маппинга](../../home/mapping/#микросервисы). | Название | Обязательность | Описание | Значение по умолчанию | | ------------------------ | -------------- | ---------------------------------------------------------------------------------------- | --------------------- | | targetRepositoryUrl | Да | HTTPS-адрес репозитория микросервиса | Роль `microservice_repository` | | targetBranch | Нет | Ветка, от которой создаётся ветка обновления | Роль `microservice_default_branch`, затем «Ветка по умолчанию» реестра шаблонов, затем `main` | | sourceBranch | Нет | Ветка, в которую записываются изменения | `<префикс ветки обновления><версия>`, например `ddp/template-upgrade-1.3.0` | -| templateId | Да | Идентификатор шаблона | Роль `microservice_binding_template_id` | -| templatePackSource | Да | Название подключения в реестре шаблонов | Роль `microservice_binding_template_source` | +| templateId | Да | Идентификатор шаблона | Параметр `ddp_template_id` | +| templatePackSource | Да | Название подключения в реестре шаблонов | Параметр `ddp_template_source` | | templateVersion | Нет | Целевая версия шаблона в формате semver | Последняя версия шаблона | | upgradeStrategy | Нет | Стратегия обновления: `selective`, `additive`, `selective_additive`, `full` или `merge` | Параметр микросервиса, затем стратегия пакета, затем `selective` | | updateOverwrite | Нет | Glob-шаблоны перезаписываемых путей | Параметр микросервиса, затем список пакета | diff --git a/content/documentation/admin/actions/overview.ru.md b/content/documentation/admin/actions/overview.ru.md index c725eaa4..693d99d3 100644 --- a/content/documentation/admin/actions/overview.ru.md +++ b/content/documentation/admin/actions/overview.ru.md @@ -314,6 +314,8 @@ project_id: {{ .property.project_id }} Синхронизация запускается после успешного выполнения действия и применения правил обновления. Синхронизация выполняется в фоне: действие не ожидает её завершения и не завершается ошибкой, если синхронизация не удалась. Удалённые источники данных пропускаются. +Чтобы следующий шаг процесса выполнялся после обновления каталога, добавьте после действия элемент [«Источник данных»](../processes/overview/#источник-данных) с теми же источниками. Выберите «Подождать текущую синхронизацию», чтобы дождаться уже запрошенного запуска, или «Нужны свежие данные», если требуется чтение источника после входа в этот шаг. + ### Безопасность #### Условия выполнения diff --git a/content/documentation/admin/ai-agents/agent-sources.ru.md b/content/documentation/admin/ai-agents/agent-sources.ru.md index 0e60e802..6c7889f8 100644 --- a/content/documentation/admin/ai-agents/agent-sources.ru.md +++ b/content/documentation/admin/ai-agents/agent-sources.ru.md @@ -42,8 +42,8 @@ AI-агенты — функциональность на стадии Preview. 1. Создайте ресурс, сущности которого будут описывать агентов. Добавьте в ресурс параметр типа `String` для URL карточки агента, например `agent_card_url`. 1. Создайте сущности ресурса и заполните в них URL карточки. Идентификатор сущности станет идентификатором агента. -1. Перейдите в раздел «AI» → «AI-агенты» → «Источники агентов» и нажмите «Создать источник агентов». Кнопка доступна с разрешением `edit:ai-agents`. -1. На вкладке «Основная информация» включите «Включить источник», заполните «Название» и «Идентификатор». +1. Перейдите в раздел «AI» → «Агенты» → «Источники агентов» и нажмите «Создать источник агентов». Кнопка доступна с разрешением `edit:ai-agents`. +1. На вкладке «Основная информация» включите «Включить», заполните «Название» и «Идентификатор». 1. На вкладке «Ресурсы каталога» нажмите «Добавить ресурс», выберите ресурс и в поле «Параметр с URL Agent Card» выберите параметр с URL карточки. 1. На вкладке «Подключение» укажите «API-ключ», общий для всех агентов источника. 1. Нажмите «Сохранить», затем в меню карточки источника выберите «Синхронизировать сейчас». @@ -52,7 +52,7 @@ AI-агенты — функциональность на стадии Preview. ## Параметры источника -Форма источника состоит из вкладок «Основная информация», «Ресурсы каталога» и «Подключение». +Форма источника содержит вкладки «Основная информация», «Ресурсы каталога» и «Подключение». Коллекции задаются в настройках источника и применяются к его агентам. ### Основная информация @@ -60,7 +60,7 @@ AI-агенты — функциональность на стадии Preview. | Поле | Обязательность | Описание | | --- | --- | --- | -| «Включить источник» | — | Выключенный источник не синхронизируется и не выключает уже созданных им агентов | +| «Включить» | — | Выключенный источник не синхронизируется и не выключает уже созданных им агентов | | «Название» | Да | Название источника | | «Идентификатор» | Да | Уникальный идентификатор источника | | «Описание» | Нет | Описание источника | @@ -119,14 +119,14 @@ AI-агенты — функциональность на стадии Preview. | --- | --- | --- | | «API-ключ» | Да | Ключ, который портал передаёт каждому агенту источника в заголовках `X-A2A-Api-Key` и `Authorization: Bearer` | | «Вызывать адрес из карточки агента» | — | Если выключено, портал вызывает базовый URL карточки. Выключите для источников внутри кластера, например kagent, которые публикуют адреса, доступные только изнутри кластера | -| «MCP-инструменты» | Нет | Инструменты портала, доступные каждому агенту источника. Пустой список — агенты не получают доступа к инструментам портала | +| «MCP-коллекции» | Нет | Коллекции каждого агента источника. В запуск попадают их инструменты, которыми может пользоваться запускающий пользователь; без коллекций агенты работают без MCP-инструментов | API-ключ хранится в зашифрованном виде и после сохранения не отображается. При редактировании источника оставьте поле пустым, чтобы сохранить текущий ключ. ## Агенты из источника -У агента из источника портал при каждой синхронизации задаёт адрес карточки, API-ключ, «Вызывать адрес из карточки агента» и «MCP-инструменты» по настройкам источника. -В подключении такого агента вручную меняются только переключатель «Включить агента» и «Разрешить прокси моделей DDP». +У агента из источника портал при каждой синхронизации задаёт адрес карточки, API-ключ, «Вызывать адрес из карточки агента» и MCP-коллекции по настройкам источника. +Коллекции такого агента меняйте в источнике. В подключении агента можно менять включение и разрешение прокси моделей DDP; навыки назначаются самому агенту. Если агенту нужен прокси моделей DDP, включите «Разрешить прокси моделей DDP» в подключении агента после первой синхронизации: источник этот переключатель не меняет. diff --git a/content/documentation/admin/ai-agents/external-agents.ru.md b/content/documentation/admin/ai-agents/external-agents.ru.md index 47a77947..a9919b95 100644 --- a/content/documentation/admin/ai-agents/external-agents.ru.md +++ b/content/documentation/admin/ai-agents/external-agents.ru.md @@ -17,18 +17,18 @@ AI-агенты — функциональность на стадии Preview. Чтобы подключить внешнего агента: -1. Перейдите в раздел «AI» → «AI-агенты» → «Каталог» и нажмите «Подключить». Кнопка доступна с разрешением `edit:ai-agents`. +1. Перейдите в раздел «AI» → «Агенты» → «Каталог» и нажмите «Подключить агента». Кнопка доступна с разрешением `edit:ai-agents`. 1. На вкладке «Основная информация» заполните «Название» и «Идентификатор». -1. На вкладке «Подключение» включите переключатель «Включить агента». +1. На вкладке «Подключение» включите переключатель «Включить». 1. Укажите «URL Agent Card» — адрес карточки агента, например `https://agents.example.com/.well-known/agent-card.json`. 1. Укажите «API-ключ», который ожидает агент. 1. Нажмите «Сохранить». -Агент появится в каталоге с отметкой «Внешний». Запускать его может только владелец подключения — пользователь, который его создал. +Агент появится в каталоге с отметкой «Внешний». Для запуска предоставьте пользователю `use:ai-agents` или `use:ai-agent` на это подключение. Владение даёт права при включённом `owner-is-admin`. ## Параметры подключения -Форма подключения состоит из вкладок «Основная информация» и «Подключение». +Форма подключения содержит вкладки «Основная информация», «Подключение» и «Инструменты и навыки». ### Основная информация @@ -44,16 +44,17 @@ AI-агенты — функциональность на стадии Preview. ### Подключение -Поля вкладки «Подключение» отображаются, когда включён переключатель «Включить агента»: +Поля вкладки «Подключение» отображаются, когда включён переключатель «Включить»: | Поле | Обязательность | Описание | | --- | --- | --- | -| «Включить агента» | — | Выключенный агент не отображается в AI-ассистенте, виджетах и шагах процессов | +| «Включить» | — | Выключенный агент не отображается в AI-ассистенте, виджетах и шагах процессов | | «URL Agent Card» | Да | Адрес карточки агента. Портал читает из карточки название, описание и адреса, по которым принимает вызовы агент | | «Вызывать адрес из карточки агента» | — | Если включено, портал вызывает адрес, объявленный в карточке. Если выключено, портал вызывает базовый URL карточки — адрес из поля «URL Agent Card» без `/.well-known/agent-card.json` или `/.well-known/agent.json` | | «Разрешить прокси моделей DDP» | — | Агент обращается к языковой модели через портал и использует AI-провайдера пользователя, который запустил задачу. Подробнее — в разделе [«Языковая модель агента»](overview/#языковая-модель-агента) | | «API-ключ» | Да | Ключ, который портал передаёт агенту в заголовках `X-A2A-Api-Key` и `Authorization: Bearer` при каждом вызове и при чтении карточки | -| «MCP-инструменты» | Нет | Инструменты портала, которые может вызывать агент. Пустой список — агент не получает доступа к инструментам портала | + +На вкладке «Инструменты и навыки» выберите «MCP-коллекции» и при необходимости [навыки](skills/). Агент получает инструменты этих коллекций, которыми может пользоваться запускающий пользователь. Без коллекций агент работает без MCP-инструментов. Доступ к инструментам задаётся [коллекциями и ролями](../../user/mcp-management/#связь-с-ai-ассистентом-и-mcp-сервером). API-ключ хранится в базе данных в зашифрованном виде и после сохранения не отображается. При редактировании подключения оставьте поле «API-ключ» пустым, чтобы сохранить текущий ключ. @@ -76,9 +77,9 @@ API-ключ хранится в базе данных в зашифрованн | Ключ | Когда передаётся | Значение | | --- | --- | --- | -| `ddp.mcp.endpoint` | Список «MCP-инструменты» не пуст | Адрес MCP-эндпоинта портала, например `https:///api/v2/agent-mcp` | -| `ddp.mcp.runToken` | Список «MCP-инструменты» не пуст | Токен запуска | -| `ddp.mcp.toolAllowlist` | Список «MCP-инструменты» не пуст | Инструменты, разрешённые в этом запуске | +| `ddp.mcp.endpoint` | Есть разрешённые инструменты в коллекциях | Адрес MCP-эндпоинта портала, например `https:///api/v2/agent-mcp` | +| `ddp.mcp.runToken` | Есть разрешённые инструменты в коллекциях | Токен запуска | +| `ddp.mcp.toolAllowlist` | Есть разрешённые инструменты в коллекциях | Инструменты, разрешённые в этом запуске | | `ddp.llm.baseUrl` | Включён переключатель «Разрешить прокси моделей DDP» | Адрес прокси моделей, например `https:///api/v2/agent-llm/v1` | | `ddp.llm.apiKey` | Включён переключатель «Разрешить прокси моделей DDP» | Токен запуска | | `ddp.llm.model` | Включён переключатель «Разрешить прокси моделей DDP» | Модель AI-провайдера пользователя | @@ -106,6 +107,8 @@ curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-T Инструмент, которого нет в `ddp.mcp.toolAllowlist`, возвращает ошибку `403`. Недействительный или отозванный токен — ошибку `401`. +Этот эндпоинт принимает названия из списка инструментов без префикса агента: `get_resources`, `query_catalog`, `curated_get_skill`. Префикс `ddp_` платформенный агент добавляет только при передаче инструментов модели. При реализации внешнего агента сохраняйте соответствие между названием для модели и названием, отправляемым порталу. + ### Обращение к модели через портал Если агенту разрешён прокси моделей DDP, он обращается к `/chat/completions` как к API OpenAI Chat Completions и передаёт `ddp.llm.apiKey` как API-ключ. @@ -142,7 +145,7 @@ curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-T ## Изменение и удаление -Изменять и удалять подключение могут его владелец, участники команды-владельца и супер-администратор. +Изменять и удалять подключение можно с глобальным `edit:ai-agents` или объектным `edit:ai-agent`. При включённом `owner-is-admin` эти права также получают владелец и участники команды-владельца; супер-администратор имеет доступ ко всем подключениям. Чтобы изменить или удалить подключение, выберите «Редактировать» или «Удалить» в меню карточки агента в каталоге. Если выключить агента вручную, он не включится автоматически, даже если им управляет источник агентов. @@ -158,4 +161,4 @@ curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-T | «Внешний агент отклонил учётные данные. Проверьте API-ключ его ссылки.» | Агент не принял API-ключ. Укажите в подключении ключ, который ожидает агент | | «Внешний агент недоступен (ошибка сети или таймаут). Попробуйте позже.» | Агент не ответил вовремя или недоступен по сети | | «Внешний агент не вернул ответ.» | Задача агента завершилась без итогового сообщения | -| «Недостаточно прав для запуска этого AI-агента» | Внешнего агента запускает только владелец подключения | +| «Недостаточно прав для запуска этого AI-агента» | Проверьте глобальное `use:ai-agents` или объектное `use:ai-agent` на подключение | diff --git a/content/documentation/admin/ai-agents/overview.ru.md b/content/documentation/admin/ai-agents/overview.ru.md index 4a7bdde6..edf8548f 100644 --- a/content/documentation/admin/ai-agents/overview.ru.md +++ b/content/documentation/admin/ai-agents/overview.ru.md @@ -1,116 +1,91 @@ --- title: Обзор weight: 10 -description: Как устроены AI-агенты в DDP — виды агентов, где они запускаются, откуда берут модель и инструменты, какие разрешения нужны. +description: Виды AI-агентов DDP, модель доступа, MCP-коллекции, навыки и запуск в чате, виджете и процессе. --- {{< alert level="warning" >}} AI-агенты — функциональность на стадии Preview. Виды агентов, состав настроек и API могут измениться в следующих выпусках без сохранения обратной совместимости. {{< /alert >}} -AI-агент — программа, которая получает задачу на естественном языке, обращается к языковой модели и вызывает инструменты, чтобы подготовить ответ или выполнить работу. -Deckhouse Development Portal (DDP, портал) запускает агентов по протоколу [A2A (Agent2Agent)](https://a2a-protocol.org/) версии 1.0 и передаёт им доступ к своим инструментам MCP и, при необходимости, к языковой модели. +AI-агент получает задачу на естественном языке, обращается к языковой модели и вызывает инструменты для подготовки ответа или выполнения работы. Deckhouse Development Portal (DDP) подключает агентов по протоколу A2A (Agent2Agent) версии 1.0. -Агенты используются в трёх местах портала: - -- в [AI-ассистенте](../../user/ai-assistant/) — пользователь выбирает агента в окне ассистента; -- в виджете [«AI-чат»](../widgets/ai/chat/) — агент задаётся в настройках виджета; -- в процессах — элемент [«AI-агент»](../processes/overview/#ai-агент) отправляет агенту задачу и записывает результат в хранилище процесса. +Агенты из каталога используются в [AI-ассистенте](../../user/ai-assistant/), виджете [«AI-чат»](../widgets/ai/chat/) и элементе процесса [«AI-агент»](../processes/overview/#ai-агент). Для работы с файлами проекта доступен также отдельный [агент рабочего пространства](../../user/workspaces/). ## Виды агентов -Каждый агент в портале — подключение к его карточке агента (Agent Card), то есть к JSON-описанию, которое агент публикует по адресу `/.well-known/agent-card.json`. -По способу подключения агенты делятся на виды: +Подключение агента задаётся его карточкой Agent Card, которую агент публикует как JSON, обычно по адресу `/.well-known/agent-card.json`: -| Вид | Как появляется | Отметка в каталоге | -| --- | --- | --- | -| [Платформенный агент](platform-agent/) | Разворачивается вместе с порталом и подключается автоматически. Идентификатор — `ddp-agent` | «Платформенный» | -| [Внешний агент](external-agents/) | Администратор подключает его вручную по URL карточки и API-ключу | «Внешний» | -| [Агент из источника](agent-sources/) | Источник агентов создаёт его по сущности каталога | «Внешний» и «Из источника» | +| Вид | Подключение | +| --- | --- | +| [Платформенный агент](platform-agent/) | Разворачивается с порталом и подключается автоматически, идентификатор `ddp-agent` | +| [Внешний агент](external-agents/) | Подключается администратором по URL карточки и API-ключу | +| [Агент из источника](agent-sources/) | Создаётся источником по сущности каталога | -Все агенты выполняются вне процесса портала: портал отправляет агенту сообщение по A2A и ждёт ответа. +Портал отправляет агенту сообщение по A2A и получает ответ. Сам агент выполняется вне backend портала. ## Языковая модель агента -Агент обращается к языковой модели одним из способов: +Агент использует собственные доступы к модели или прокси моделей DDP. При работе через прокси портал использует AI-провайдера пользователя, запустившего задачу, и расходует его квоту. -- **Собственная модель.** Агент использует свои доступы к модели. AI-провайдер портала ему не нужен. -- **Прокси моделей DDP.** Портал передаёт агенту адрес прокси и короткоживущий токен запуска. Агент обращается к модели через портал, а портал использует [AI-провайдера](../../user/ai-assistant/#подключение-ai-провайдера) пользователя, который запустил задачу, и расходует его квоту. +В каталоге источник модели отображается как «Модель DDP» или «Модель агента». -Платформенный агент всегда работает через прокси моделей DDP. -Внешнему агенту прокси доступен, только если в настройках подключения включён переключатель «Разрешить прокси моделей DDP». +Платформенный агент всегда использует прокси. Для внешнего агента включите «Разрешить прокси моделей DDP» в настройках подключения, если модель должен предоставлять портал. -Прокси отправляет запросы в формате OpenAI Chat Completions по адресу `/chat/completions`; если URL уже оканчивается на `/chat/completions`, суффикс не дублируется. -Поэтому через прокси работают только AI-провайдеры с API, совместимым с OpenAI Chat Completions, у которых заданы модель и токен. -Поля провайдера «Шаблон тела запроса» и «Поле ответа» прокси не использует. +Прокси работает с API, совместимым с OpenAI Chat Completions: к URL провайдера добавляется `/chat/completions`, если суффикса ещё нет. Требуются модель и токен; поля провайдера «Шаблон тела запроса» и «Поле ответа» для агентского запроса не используются. -Прокси не поддерживает потоковые ответы (`stream: true`) и всегда подставляет модель из AI-провайдера, игнорируя модель из запроса агента. +Прокси не поддерживает `stream: true` и подставляет модель AI-провайдера вместо модели из запроса агента. ## Инструменты агента -Агент вызывает инструменты портала через отдельный MCP-эндпоинт `/api/v2/agent-mcp`. -Список инструментов, доступных агенту, задаёт поле «MCP-инструменты» в настройках подключения: +На вкладке «Инструменты и навыки» задайте «MCP-коллекции». Агент получает инструменты включённых коллекций, которыми может пользоваться запускающий пользователь через свои коллекции. Проверка прав на объекты портала выполняется отдельно при каждом вызове. -- пустой список — агент не получает доступа к инструментам портала; -- непустой список — агент может вызывать только перечисленные инструменты. +Без коллекций агент работает без MCP-инструментов. Это правило одинаково для платформенного агента, внешних агентов, чата, виджетов и процессов. Состав коллекции может включать инструменты портала, подключённых MCP-серверов и пользовательские HTTP-инструменты. -Инструменты выполняются с правами пользователя, который запустил задачу. -Описание встроенных инструментов — в разделе [«MCP-сервер»](../../user/mcp-server/#доступные-инструменты). +Например, чтобы агент читал каталог, включите `get_resources` и `get_resource_entities` в коллекцию, подключите её к агенту и предоставьте пользователю право использовать её. Для запуска процессов добавьте `curated_get_processes`, `curated_run_process` и `curated_get_process_instance`. -## Токен запуска +Пошаговая настройка — [в руководстве по MCP-коллекциям](../../user/mcp-management/#mcp-коллекции). -На каждый запуск агента портал выпускает токен запуска и передаёт его агенту в метаданных сообщения A2A. -Токен даёт доступ к эндпоинтам `/api/v2/agent-mcp` и `/api/v2/agent-llm` от имени пользователя, который запустил задачу. +Для поиска, подсчёта и группировки сущностей, анализа связей и диагностики процессов добавьте группу «Обозреватель каталога» в MCP-коллекцию агента и предоставьте пользователям право использовать коллекцию. Доступ к коллекции не заменяет права на ресурсы, сущности, процессы и действия. Состав инструментов и примеры вызовов — [в справочнике MCP](../../user/mcp-server/#инструменты-работы-с-каталогом). -Токен действует, пока запуск находится в статусе «Выполняется», но не дольше 75 минут. -После завершения или остановки запуска портал отзывает токен, и следующий вызов инструмента или модели агентом завершается ошибкой `401`. +В коллекциях используются названия `get_resources`, `curated_run_process` и `curated_get_skill`. В инструкциях платформенному агенту добавляйте префикс `ddp_`: `ddp_get_resources`, `ddp_curated_run_process`, `ddp_curated_get_skill`. Полная [схема названий инструментов](../../user/mcp-server/#названия-инструментов) учитывает и вызовы из внешнего MCP-клиента. -## Навигация +## Навыки агента -Агенты настраиваются в разделе «AI» → «AI-агенты»: +На той же вкладке назначьте [навыки](skills/) с конкретной версией или привязкой «Последняя». При запуске агент получает их названия и описания, полный текст читает через `curated_get_skill` при необходимости. Этот инструмент должен быть доступен через коллекции агента и пользователя. -| Пункт меню | Назначение | Разрешение для просмотра | -| --- | --- | --- | -| «Каталог» | Список агентов, подключение внешних агентов, настройка инструментов | `read:ai-agents` | -| «Источники агентов» | [Источники агентов](agent-sources/) из каталога | `read:ai-agents` | -| «История запусков» | [Запуски агентов](runs/) текущего пользователя | `read:ai-agent-runs` | -| «Шаблоны AI-провайдеров» | [Шаблоны AI-провайдеров](provider-templates/) для пользователей портала | `edit:ai-provider-templates` | +Для инструкций и материалов в GitLab настройте [источник навыков](skill-sources/). -## Разрешения +## Доступ к агентам -Работа с агентами регулируется глобальными разрешениями: +Использование регулируется глобальным `use:ai-agents` или объектным `use:ai-agent` для конкретного подключения. Право действует для чата, виджета и шага процесса. Оно не предоставляет доступ к данным каталога и не выдаёт инструменты MCP. -| Разрешение | Что даёт | -| --- | --- | -| `run:ai-agents` | Работа с AI-ассистентом и виджетом «AI-чат», запуск платформенного агента | -| `run:ai-agents-a2a` | Запуск платформенного агента в шагах процессов. AI-ассистент и виджет «AI-чат» с этим разрешением недоступны | -| `read:ai-agents` | Просмотр каталога агентов и источников агентов | -| `edit:ai-agents` | Подключение, изменение и удаление внешних агентов и источников агентов, синхронизация источников | -| `read:ai-agent-runs` | Просмотр истории своих запусков агентов | -| `cancel:ai-agent-runs` | Остановка своих запусков агентов | -| `read:ai-provider-templates` | Просмотр шаблонов AI-провайдеров, включая отключённые | -| `edit:ai-provider-templates` | Создание, изменение и удаление шаблонов AI-провайдеров | +Просмотр и изменение регулируются отдельными правами: + +| Объект | Глобальные разрешения | Разрешения конкретного объекта | +| --- | --- | --- | +| Агент | `read:ai-agents`, `edit:ai-agents` | `read:ai-agent`, `edit:ai-agent`, `use:ai-agent` | +| Источник агентов | `read:ai-agents`, `edit:ai-agents` | `read:ai-agent-source`, `edit:ai-agent-source` | +| Шаблон AI-провайдера | `read:ai-provider-templates`, `edit:ai-provider-templates`, `use:ai-provider-templates` | `read:ai-provider-template`, `edit:ai-provider-template`, `use:ai-provider-template` | -Кроме глобальных разрешений, действуют правила владения: +Владение и участие в команде-владельце предоставляют права при включённом `owner-is-admin`. Доступ можно выдать другим пользователям и командам через «Настроить доступ». Супер-администратор имеет доступ ко всем подключениям. -- внешнего агента и агента из источника запускает только владелец подключения; -- изменять и удалять подключение могут владелец и участники команды-владельца; -- платформенного агента может запустить любой пользователь с `run:ai-agents`, а изменить его настройки — только супер-администратор. +История своих запусков требует `read:ai-agent-runs`, остановка — `cancel:ai-agent-runs`. Для раздела «AI» требуется `view:ai-page`; само по себе это разрешение не выдаёт доступ к его объектам. -Супер-администратор видит, запускает и изменяет все подключения. -Полный список разрешений — в разделе [«Ролевая модель»](../security/rbac/). +## Токен запуска и ограничения -## Ограничения +Для разрешённых обращений к MCP и прокси моделей портал передаёт короткоживущий токен запуска. После завершения или остановки запуска токен отзывается. -На запуски агентов действуют ограничения: +Для запусков A2A-агентов действуют ограничения: | Ограничение | Значение | | --- | --- | | Максимальная длительность запуска | 70 минут | -| Вызовы инструментов портала | 120 в минуту на один запуск | -| Запросы к прокси моделей DDP | 60 в минуту на один запуск | -| Размер запроса к прокси моделей DDP | 1 МиБ | +| Максимальный срок токена | 75 минут | +| Вызовы MCP | 120 в минуту на запуск | +| Запросы к прокси моделей | 60 в минуту на запуск | +| Размер запроса к прокси | 1 МиБ | | Размер ответа модели через прокси | 4 МиБ | -| Тайм-аут запроса к модели через прокси | 90 секунд | +| Тайм-аут запроса к модели | 90 секунд | -При запуске backend и затем раз в сутки портал проверяет зависшие запуски: запуск, который находится в статусе «Выполняется» дольше 75 минут, получает статус «Ошибка» с текстом `agent run interrupted (stale)`. +Ошибки и результаты проверяйте [в истории запусков](runs/), сводные показатели — [в статистике AI](../../user/ai-statistics/). diff --git a/content/documentation/admin/ai-agents/platform-agent.ru.md b/content/documentation/admin/ai-agents/platform-agent.ru.md index a4797da8..5096d1ae 100644 --- a/content/documentation/admin/ai-agents/platform-agent.ru.md +++ b/content/documentation/admin/ai-agents/platform-agent.ru.md @@ -1,139 +1,63 @@ --- title: Платформенный агент weight: 20 -description: Платформенный AI-агент ddp-agent — как он разворачивается и подключается, что требуется пользователям для работы с ним, как расширить набор его инструментов. +description: Подготовка платформенного агента ddp-agent к работе, доступ пользователей, MCP-коллекции, навыки и диагностика. --- -{{< alert level="warning" >}} -AI-агенты — функциональность на стадии Preview. Виды агентов, состав настроек и API могут измениться в следующих выпусках без сохранения обратной совместимости. -{{< /alert >}} +Платформенный агент с идентификатором `ddp-agent` разворачивается вместе с Deckhouse Development Portal (DDP). Он доступен в AI-ассистенте, виджете «AI-чат» и шагах процессов. -Платформенный агент — AI-агент с идентификатором `ddp-agent`, который разворачивается вместе с порталом. -По умолчанию именно он отвечает в [AI-ассистенте](../../user/ai-assistant/) и в виджете [«AI-чат»](../widgets/ai/chat/), его же можно выбрать в элементе процесса [«AI-агент»](../processes/overview/#ai-агент). +Агент использует языковую модель через AI-провайдера запускающего пользователя. В каталоге он отмечен как «Модель DDP»; переключатель «Разрешить прокси моделей DDP» в его подключении включён и недоступен для изменения. Для работы с файлами проекта используйте [рабочее пространство](../../user/workspaces/). -Агент отвечает на языке пользователя и находит объекты портала сам: сначала получает список ресурсов, затем сущности ресурса, затем данные сущности и её связи. -Идентификаторы и UUID агент берёт только из ответов инструментов и не запрашивает их у пользователя. - -## Как разворачивается агент - -Модуль `development-platform` разворачивает агента в неймспейсе `d8-development-platform` как Deployment `agent`. -Агент доступен только внутри кластера по адресу `http://agent:8080`, Ingress для него не создаётся. +## Быстрый старт -Агент не настраивается в ModuleConfig: +Чтобы пользователи работали с агентом и данными каталога: -- модуль один раз генерирует API-ключ агента и сохраняет его в Secret `agent-secret-envs`; при обновлении модуля ключ не меняется; -- при запуске backend и затем раз в минуту портал проверяет подключение `ddp-agent` и, если его нет, создаёт; если адрес карточки, ключ или базовый набор инструментов изменились, портал восстанавливает их. +1. Выдайте доступ к агенту через глобальное `use:ai-agents` или объектное `use:ai-agent`. Для раздела «AI» добавьте `view:ai-page`. +1. Подготовьте [AI-провайдера](../../user/ai-assistant/#подключение-ai-провайдера) или [шаблон с общим токеном](provider-templates/). +1. Создайте включённую MCP-коллекцию с инструментами `get_resources` и `get_resource_entities`. +1. Предоставьте пользователю право использовать эту коллекцию и права чтения нужных объектов каталога. +1. В каталоге агентов откройте редактирование платформенного агента. На вкладке «Инструменты и навыки» выберите коллекцию в «MCP-коллекции» и сохраните. +1. В AI-ассистенте выберите агента и провайдера, затем попросите показать доступные ресурсы каталога. -Агент не хранит доступов к языковой модели: на каждый запуск портал передаёт ему доступ к прокси моделей DDP и AI-провайдера пользователя, который запустил задачу. -Подробнее — в разделе [«Языковая модель агента»](overview/#языковая-модель-агента). +Пустой набор коллекций означает работу без MCP-инструментов. Портал не восстанавливает автоматически прежний набор инструментов чтения. -## Быстрый старт +## Изменение инструментов и навыков -Чтобы пользователи могли работать с платформенным агентом: +Для расширения возможностей отредактируйте коллекцию или подключите другую. Например, для процессов добавьте `curated_get_processes`, `curated_run_process` и `curated_get_process_instance`. Пользователю также необходимы доступ к этим инструментам через коллекции и разрешения на операции с сущностями. -1. Убедитесь, что агент работает. Выполните запрос к эндпоинту состояния портала: +На вкладке «Инструменты и навыки» можно назначить [навыки](skills/). Для их чтения в запуске должен быть доступен `curated_get_skill`. - ```shell - curl -s https:///healthz - ``` +При добавлении группы портала целиком новые инструменты этой группы автоматически входят в коллекцию. Если состав должен быть фиксированным, выбирайте отдельные инструменты. - где `` — домен портала. В ответе поле `agents` должно иметь значение `ok`. +## Развёртывание и настройки -1. Выдайте пользователям роль с глобальным разрешением `run:ai-agents`. Для доступа к разделу «AI» добавьте в роль `view:ai-page`. Подробнее о ролях — в разделе [«Ролевая модель»](../security/rbac/#настройка-ролей-и-управление-доступом). -1. Подготовьте AI-провайдера, совместимого с OpenAI Chat Completions. Создайте [шаблон AI-провайдера](provider-templates/) с общим токеном или попросите пользователей подключить провайдера в профиле, как описано в разделе [«Подключение AI-провайдера»](../../user/ai-assistant/#подключение-ai-провайдера). -1. Откройте AI-ассистент: агент выбран в поле «Агент», провайдер — в поле рядом с полем ввода. +Модуль `development-platform` создаёт Deployment `agent` в `d8-development-platform`. Агент доступен внутри кластера по `http://agent:8080`; отдельный Ingress ему не нужен. -## Значения поля agents +Модуль задаёт API-ключ и адрес карточки. Портал создаёт подключение автоматически и проверяет его при запуске backend и раз в минуту. Название, описание, включение, коллекции и навыки задаются в подключении. Идентификатор `ddp-agent`, адрес карточки и ключ управляются установкой. -Поле `agents` в ответе эндпоинта `/healthz` показывает состояние платформенного агента и не влияет на общий статус портала: +Выключение агента убирает его из выбора в чате, виджетах и процессах. Проверка подключения не включает его обратно. Удаление подключения платформенного агента недоступно. -| Значение | Что означает | -| --- | --- | -| `ok` | Карточка агента читается, агент готов к работе | -| `unavailable` | Подключение `ddp-agent` есть, но карточка агента не читается: под `agent` не запущен или недоступен | -| `not_configured` | Подключение `ddp-agent` не создано | +## Диагностика -Чтобы проверить состояние пода агента, выполните команду: +Проверьте состояние агента через эндпоинт портала: ```shell -d8 k -n d8-development-platform get pods -l app=agent +curl -s https://ddp.example.com/healthz ``` -## Инструменты агента - -Платформенному агенту всегда доступны встроенные инструменты портала, которые только читают данные: - -- `get_resources`; -- `get_resource_entities`; -- `get_entity`; -- `get_entity_relations`; -- `get_actions`; -- `get_datasources`; -- `get_processes`; -- `get_external_services`; -- `get_process_instances`; -- `get_process_instance`. +Поле `agents` показывает состояние: -Этот набор нельзя сократить: если убрать из списка встроенный инструмент, портал вернёт его при следующей проверке подключения. - -В AI-ассистенте и виджете «AI-чат» агенту также автоматически доступны пользовательские MCP-инструменты из [MCP-коллекций](../../user/mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. -В шагах процессов агент получает только инструменты из списка «MCP-инструменты». - -### Добавление инструментов - -Остальные встроенные инструменты изменяют данные или запускают процессы, поэтому по умолчанию не входят в набор агента: - -| Инструмент | Что делает | +| Значение | Значение для пользователя | | --- | --- | -| `get_external_data` | Выполняет HTTP-запрос к внешнему сервису, в том числе `POST`, `PUT`, `PATCH` и `DELETE` | -| `get_service_templates` | Получает шаблоны микросервисов | -| `run_process` | Запускает процесс для сущности | - -Чтобы добавить инструменты платформенному агенту: - -1. Войдите в портал как супер-администратор. -1. Перейдите в раздел «AI» → «AI-агенты» → «Каталог». -1. В меню карточки агента с отметкой «Платформенный» выберите «Редактировать». -1. На вкладке «Подключение» добавьте инструменты в поле «MCP-инструменты». -1. Нажмите «Сохранить». - -Добавленные инструменты сохраняются при проверках подключения. +| `ok` | Карточка читается, агент готов к работе | +| `unavailable` | Подключение есть, карточка недоступна | +| `not_configured` | Подключение не создано | -## Изменяемые параметры +При недоступности проверьте под и его логи: -В подключении платформенного агента изменяются только «Название», «Описание», «Включить агента» и «MCP-инструменты». -Идентификатор, адрес карточки и API-ключ задаёт модуль, их нельзя изменить. Подключение нельзя удалить. - -Если выключить переключатель «Включить агента», агент перестаёт отображаться в AI-ассистенте, виджетах и шагах процессов. -Портал не включает агента обратно при проверке подключения. - -## Устранение неполадок - -### Агент недоступен - -Если в AI-ассистенте отображается ошибка «Не удалось получить Agent Card внешнего агента. Проверьте URL карточки и доступность агента.» или «Внешний агент недоступен (ошибка сети или таймаут). Попробуйте позже.»: - -1. Проверьте поле `agents` в ответе `/healthz`. -1. Проверьте, что под `agent` запущен и находится в состоянии `Running`. -1. Если под перезапускается, посмотрите его логи: - - ```shell - d8 k -n d8-development-platform logs deploy/agent - ``` - -### Не настроен AI-провайдер - -Если отображается ошибка «Для вашей учётной записи не настроен AI-провайдер. Добавьте его в настройках профиля.», у пользователя нет AI-провайдера. -Подключите провайдера в профиле или выдайте пользователю доступ к шаблону AI-провайдера с общим токеном. - -Если провайдер есть, но агент не может ответить, проверьте провайдера: - -- в провайдере заданы модель и токен; -- URL провайдера указывает на API, совместимый с OpenAI Chat Completions, и оканчивается на `/v1` или `/v1/chat/completions`. - -Текст ошибки запуска отображается в [истории запусков](runs/). - -### Недостаточно прав +```shell +d8 k -n d8-development-platform get pods -l app=agent +d8 k -n d8-development-platform logs deploy/agent +``` -Ошибка «Недостаточно прав для запуска этого AI-агента» означает, что у пользователя нет разрешения `run:ai-agents`. -Добавьте разрешение в роль пользователя. +При отказе в доступе проверьте `use:ai-agents` или `use:ai-agent`. Если агент отвечает без данных каталога, проверьте коллекции агента, доступ пользователя к инструментам и его права на сущности. Ошибки модели проверяйте в AI-провайдере и [истории запусков](runs/). diff --git a/content/documentation/admin/ai-agents/provider-templates.ru.md b/content/documentation/admin/ai-agents/provider-templates.ru.md index 276a2497..225fa0f0 100644 --- a/content/documentation/admin/ai-agents/provider-templates.ru.md +++ b/content/documentation/admin/ai-agents/provider-templates.ru.md @@ -28,11 +28,13 @@ AI-провайдер нужен пользователю для работы с Чтобы создать шаблон: -1. Перейдите в раздел «AI» → «AI-агенты» → «Шаблоны AI-провайдеров». Раздел доступен с разрешением `edit:ai-provider-templates`. +1. Перейдите в раздел «AI» → «Агенты» → «Шаблоны провайдеров». Создание доступно с глобальным `edit:ai-provider-templates`; просмотр и изменение существующих шаблонов также могут быть разрешены объектными ролями. 1. Нажмите «Создать». 1. Заполните поля шаблона, как описано в разделе [«Параметры шаблона»](#параметры-шаблона). 1. Нажмите «Сохранить». +Для предварительной подготовки сохраните шаблон выключенным. Выключенное состояние сохраняется при создании; включите шаблон, когда он будет готов к использованию. + ## Параметры шаблона Форма шаблона содержит поля: @@ -73,12 +75,12 @@ AI-провайдер нужен пользователю для работы с ## Доступ к шаблону -Шаблон с личным токеном может подключить любой пользователь портала. +Использование шаблона требует глобального `use:ai-provider-templates` или объектного `use:ai-provider-template`. Владение предоставляет права при включённом `owner-is-admin`. Это относится к шаблонам с личным и общим токеном. -Шаблон с общим токеном доступен супер-администратору и пользователям, которым выдана роль с разрешением `use:ai-provider-templates` на этот шаблон. +Для шаблона с общим токеном доступ автоматически создаёт провайдера у пользователя. На конкретный шаблон выдавайте объектное `use:ai-provider-template`; глобальное `use:ai-provider-templates` даёт доступ ко всем шаблонам. Чтобы выдать доступ, в меню карточки шаблона выберите «Настроить доступ» и создайте привязку роли для пользователей или команд. -Отключённые шаблоны видят только пользователи с разрешением `read:ai-provider-templates` или `edit:ai-provider-templates`. +Отключённые шаблоны видны пользователям с правами чтения или изменения шаблона, выданными глобально или на объект. Остальным пользователям заголовки шаблона показываются только со значениями-подстановками. ## Провайдер из шаблона у пользователя diff --git a/content/documentation/admin/ai-agents/runs.ru.md b/content/documentation/admin/ai-agents/runs.ru.md index e2dcb4df..ca6fcca4 100644 --- a/content/documentation/admin/ai-agents/runs.ru.md +++ b/content/documentation/admin/ai-agents/runs.ru.md @@ -13,7 +13,7 @@ AI-агенты — функциональность на стадии Preview. ## История запусков -История открывается в разделе «AI» → «AI-агенты» → «История запусков» и доступна с разрешением `read:ai-agent-runs`. +История открывается в разделе «AI» → «Использование» → «Аудит», на вкладке «Запуски агентов», и доступна с разрешением `read:ai-agent-runs`. Пользователь видит только свои запуски, супер-администратор — запуски всех пользователей. Таблицу запусков можно отфильтровать по полям: diff --git a/content/documentation/admin/ai-agents/skill-sources.ru.md b/content/documentation/admin/ai-agents/skill-sources.ru.md new file mode 100644 index 00000000..2353c5ae --- /dev/null +++ b/content/documentation/admin/ai-agents/skill-sources.ru.md @@ -0,0 +1,53 @@ +--- +title: Навыки из GitLab +description: Подготовка репозитория навыков, настройка источника GitLab, синхронизация версий и архивирование навыков. +weight: 66 +--- + +Источник навыков синхронизирует директории из GitLab с каталогом навыков DDP. Правки выполняются в GitLab; портал публикует неизменяемые версии. + +## Структура репозитория + +Разместите навыки в непосредственных поддиректориях выбранного пути, каждый со своим `SKILL.md`: + +```text +skills/ + project-check/ + SKILL.md + references/ + checklist.md + release-prepare/ + SKILL.md + scripts/ + check.sh +``` + +Название директории навыка должно совпадать с `name` его `SKILL.md`. Формат файла и ограничения описаны [в руководстве по навыкам](skills/). + +## Подключение источника + +Для синхронизации подготовьте подключение GitLab и реквизиты пользователя с доступом к проекту. Затем выполните шаги: + +1. Откройте «AI» → «Навыки» → «Источники навыков» и нажмите «Создать источник». +1. Задайте название, идентификатор, владельца и команду источника. +1. На вкладке «Репозиторий» выберите «Внешний сервис GitLab» и «Пользователь для реквизитов». +1. Укажите «Проект» как `group/project` или числовой идентификатор, «Ветка или тег» и «Директория с навыками», например `skills`. Для корня репозитория используйте `.`. +1. На вкладке «Синхронизация» задайте «Расписание (cron)» и включите «Синхронизировать по расписанию», если нужна автоматическая синхронизация. +1. Сохраните источник и нажмите «Синхронизировать». +1. Проверьте «История синхронизаций» и созданные навыки. + +Выключенный источник можно синхронизировать кнопкой. Команда источника управляет самим источником при включённом `owner-is-admin`; навыкам источника эта команда автоматически не передаётся. + +## Публикация изменений + +При изменении содержимого директории синхронизация создаёт новую версию с меткой из первых 12 символов SHA коммита. Без изменения файлов новая версия не появляется. + +Агенты и шаблоны с привязкой «Последняя» получают новую активную версию при следующем запуске. Закреплённые привязки продолжают использовать выбранную версию. + +История синхронизаций показывает созданные, обновлённые, неизменившиеся, восстановленные, архивированные и пропущенные навыки. Для пропущенного навыка проверьте причину, формат `SKILL.md`, название директории, размеры файлов и реквизиты GitLab. + +## Удаление навыков из источника + +Если директория исчезла из репозитория, навык архивируется. Возвращение директории восстанавливает навык, архивированный источником. + +Для удаления источника его навыки должны быть в архиве. После удаления они остаются архивными ручными навыками со своими версиями. diff --git a/content/documentation/admin/ai-agents/skills.ru.md b/content/documentation/admin/ai-agents/skills.ru.md new file mode 100644 index 00000000..29faa9ed --- /dev/null +++ b/content/documentation/admin/ai-agents/skills.ru.md @@ -0,0 +1,113 @@ +--- +title: Навыки агентов +description: Создание навыка с SKILL.md, публикация версий, привязка к агентам и рабочим пространствам, установка в IDE. +weight: 65 +--- + +Навык — директория с инструкциями в `SKILL.md` и дополнительными скриптами, справочными файлами и материалами. Портал хранит версии навыков и передаёт их агентам и рабочим пространствам. + +Навык определяет, как выполнить задачу. Доступ к инструментам и объектам по-прежнему задаётся MCP-коллекциями и ролями пользователя. + +## Создание и публикация + +Чтобы создать навык подготовки изменений проекта: + +1. Откройте «AI» → «Навыки» → «Навыки» и нажмите «Создать навык». +1. Задайте название `project-check`, описание, владельца и команду. +1. Откройте черновик на вкладке «Файлы» и заполните `SKILL.md`: + + ```markdown + --- + name: project-check + description: Проверка изменений проекта перед передачей на рассмотрение. Используй после изменения файлов проекта. + metadata: + version: "1.0" + --- + + # Проверка изменений + + 1. Прочитай README.md и инструкции проекта. + 2. Определи тесты, относящиеся к изменённым файлам. + 3. Запусти эти тесты и проверь результат. + 4. Покажи список изменений, выполненные проверки и оставшиеся ограничения. + ``` + +1. При необходимости добавьте файлы кнопкой «Добавить файл»: скрипты в `scripts/`, справочные материалы в `references/`, остальные материалы в `assets/`. +1. Сохраните черновик и проверьте панель ошибок и предупреждений. +1. Нажмите «Опубликовать версию», задайте уникальную метку, например `v1`, и опубликуйте. + +Название и описание навыка определяются полями `name` и `description` в `SKILL.md`. Чтобы изменить их после создания, опубликуйте новую версию. Опубликованные файлы неизменяемы. + +## Импорт архива + +Для импорта подготовьте `tar.gz` или `zip` с одной корневой директорией, название которой совпадает с `name` в `SKILL.md`: + +```text +project-check/ + SKILL.md + references/ + checklist.md + scripts/ + check.sh +``` + +В разделе навыков выберите «Загрузить из архива», загрузите файл и проверьте содержимое и версии навыка. Допустимые размеры приведены [в ограничениях](#ограничения). + +## Подключение к агенту + +Чтобы агент получил опубликованный навык: + +1. Откройте агент в «AI» → «Агенты» → «Каталог» и выберите редактирование. +1. На вкладке «Инструменты и навыки» добавьте навык и выберите конкретную версию либо «Последняя». +1. В «MCP-коллекции» подключите коллекцию с инструментом `curated_get_skill`; для чтения дополнительных файлов добавьте также `curated_get_skill_file`. +1. Предоставьте запускающему пользователю доступ к этим инструментам через доступные ему MCP-коллекции. +1. Сохраните агента и начните новый запуск. + +При запуске агент получает названия и описания назначенных навыков и загружает полный текст при необходимости. Без доступного `curated_get_skill` набор навыков не передаётся; форма привязок показывает предупреждение. `curated_list_skills` предназначен для обычного MCP-клиента; агент получает свой подготовленный набор. + +Если инструкция в `SKILL.md` прямо называет MCP-инструмент для платформенного агента, укажите его название с префиксом `ddp_`, например `ddp_curated_get_skill_file` или `ddp_query_catalog`. В каталоге коллекций те же инструменты называются `curated_get_skill_file` и `query_catalog`. + +Привязка «Последняя» выбирает активную версию с наибольшим номером при следующем запуске. Закреплённая привязка сохраняет выбранную версию. + +## Подключение к рабочему пространству + +Откройте [шаблон рабочего пространства](../workspaces/templates/), вкладку «Навыки», и добавьте нужные навыки. Для каждой привязки выберите версию или «Последняя». + +Набор фиксируется при создании и каждом запуске пространства. Новая версия навыка не заменяет набор в работающем пространстве немедленно; остановите и снова запустите его. На карточке пространства видны зафиксированные навыки и доступные обновления. + +Для шаблона с Git настройте «Разрешить навыки из репозитория». При выключенном переключателе поле «Скрытые директории навыков» задаёт пути, исключаемые из рабочей копии. Например, `.agents/skills` или `**/skills`. + +Скрытие использует Git sparse-checkout и не удаляет файлы из репозитория. Локальные изменения, неотслеживаемые файлы и конфликты могут остаться на диске; список таких файлов появляется предупреждением в логе запуска. Через `git show` содержимое репозитория остаётся доступным. + +## Установка в локальную IDE + +Для использования навыка вне рабочего пространства DDP откройте его карточку, блок «Установка в IDE»: + +1. Выберите «Последняя» или «Конкретная версия». +1. Создайте API-ключ портала в профиле и задайте его в переменной окружения `DDP_API_KEY` терминала. +1. Скопируйте команду из карточки и выполните её в корне локального проекта. +1. Проверьте появление `.agents/skills/project-check/SKILL.md`. + +Команда скачивает архив выбранной версии и распаковывает его в `.agents/skills`. При повторном выполнении могут замениться файлы уже установленной копии навыка. + +## Устаревшие версии и архив + +На вкладке «Версии» можно пометить версию устаревшей и указать причину. Такая версия не выбирается как «Последняя»; закреплённые привязки к ней сохраняются. Если активных версий не осталось, привязки «Последняя» пропускают навык. + +Архивный навык пропускается при новых запусках с предупреждением. Вкладка «Использование» показывает доступные пользователю агенты и шаблоны, к которым он привязан. Перед архивированием проверьте этот список. + +## Ограничения + +При подготовке навыка учитывайте ограничения: + +| Ограничение | Значение | +| --- | --- | +| Название | До 64 символов: строчные латинские буквы, цифры и одиночные дефисы между ними | +| Описание | До 1024 символов | +| Число файлов | До 1000 | +| Размер файла | До 10 МиБ | +| Общий размер навыка и импортируемого архива | До 25 МиБ | +| Число назначенных навыков | До 20 на агента или шаблон | +| Текстовый файл в редакторе и чтении через MCP | До 1 МиБ | + +Наличие скриптов, `allowed-tools`, длинного `SKILL.md` и отсутствие `metadata.version` могут давать предупреждения. Проверяйте их перед публикацией. diff --git a/content/documentation/admin/architecture/functional-architecture.ru.md b/content/documentation/admin/architecture/functional-architecture.ru.md index 415abf67..55ead638 100644 --- a/content/documentation/admin/architecture/functional-architecture.ru.md +++ b/content/documentation/admin/architecture/functional-architecture.ru.md @@ -147,6 +147,21 @@ weight: 10 * периодически предоставляет ключи подписи токенов для проверки; * интегрируется с внешними провайдерами аутентификации через стандартные протоколы (OIDC, LDAP и др.). +## Рабочие пространства + +[Рабочие пространства](../workspaces/overview/) создаются в кластере и неймспейсе шаблона. При установке модулем Jobs операций OpenTofu запускаются в неймспейсе модуля. Постоянные данные рабочих пространств хранятся на отдельных томах; состояние OpenTofu передаётся в HTTP backend портала. + +Стартовый шаблон создаёт под с контейнерами: + +| Контейнер | Назначение | +| --- | --- | +| `bootstrap` | Init-контейнер: клонирование репозитория, доставка файлов, навыков и выполнение скриптов | +| `runtime` | Агент OpenCode, который выполняет задания из чата и процессов | +| `ide` | IDE code-server с файлами того же постоянного тома | +| `gate` | Проверка доступа к IDE через портал | + +Браузер открывает IDE по отдельному HTTPS-домену через Ingress целевого кластера. Контейнер `gate` проверяет доступ в DDP. Агент обращается к модели и MCP через портал, поэтому подам нужен доступ к HTTPS-адресу DDP. Настройка описана [в примерах сети и хранения](../workspaces/network-storage/). + ## Описание сетевых взаимодействий ![Сетевые взаимодействия компонентов DDP](../images/functional-architecture/ddp-network-flows.ru.svg) diff --git a/content/documentation/admin/architecture/workers.ru.md b/content/documentation/admin/architecture/workers.ru.md index 166d1eaf..c1287a11 100644 --- a/content/documentation/admin/architecture/workers.ru.md +++ b/content/documentation/admin/architecture/workers.ru.md @@ -10,6 +10,7 @@ weight: 20 - Запуск действий и процессов. - Проверки статуса сущностей. - Запуски AI-агентов из элементов процессов «AI-агент». +- Периодическая синхронизация каталогов внешних MCP-серверов. Воркеры работают независимо от основного приложения и позволяют масштабировать нагрузку на систему, перенося ресурсоёмкие операции на выделенные реплики. @@ -72,6 +73,10 @@ weight: 20 Воркеры выполняют запуски [AI-агентов](../ai-agents/overview/) из элементов процессов «AI-агент»: отправляют задачу агенту по протоколу A2A и ждут её завершения. Длительность одного запуска ограничена 70 минутами. Пока запуск выполняется, он занимает одну из `workers.maxTasks` параллельных задач воркера. +### Синхронизация MCP-серверов + +Периодическая синхронизация каталогов MCP-серверов выполняется воркерами. Включите её в настройках сервера и задайте системную учётную запись. При неудачной попытке сохраняется предыдущий каталог; результаты и время обновления доступны в карточке сервера. Настройка — [в руководстве по MCP](../../user/mcp-management/#автоматическая-синхронизация). + ## Фоновые операции с данными в ClickHouse Если подключён [ClickHouse](../../install/#clickhouse), воркеры дополнительно переносят в него данные из PostgreSQL и убирают лишнее. Так, например, обслуживается [история изменений параметров сущностей](../../../user/catalog/#история-параметров): diff --git a/content/documentation/admin/datasets.ru.md b/content/documentation/admin/datasets.ru.md index 34e8e00d..b9bbf5a5 100644 --- a/content/documentation/admin/datasets.ru.md +++ b/content/documentation/admin/datasets.ru.md @@ -82,7 +82,7 @@ weight: 74 После применения заполните в профиле пользователя учётные данные «GitLab токен» и «GitLab username». -Группы, репозитории и виджеты GitLab для главной создают наборы данных «GitLab: группы», «GitLab: активность репозиториев» и «GitLab: виджеты». Они описаны в разделе [«Первоначальная настройка»](../home/setup/#наборы-данных-мастера). +Группы и виджеты GitLab для главной создают наборы данных «GitLab: группы» и «GitLab: виджеты». Они описаны в разделе [«Первоначальная настройка»](../home/setup/#наборы-данных-мастера). ### Kubernetes diff --git a/content/documentation/admin/datasources/overview.ru.md b/content/documentation/admin/datasources/overview.ru.md index 9b279f0b..3f8cd53e 100644 --- a/content/documentation/admin/datasources/overview.ru.md +++ b/content/documentation/admin/datasources/overview.ru.md @@ -171,7 +171,21 @@ metadata: При включённом параметре «Периодическая синхронизация» источник данных будет автоматически обновлять информацию из внешних инфраструктурных систем с интервалом, определённым в параметре «Периодичность запуска». -Также каждый источник данных может быть синхронизирован вручную в любой момент времени через веб-интерфейс (пункт «Синхронизировать» в меню источника данных), либо через API. +Также каждый источник данных может быть синхронизирован вручную в любой момент времени через веб-интерфейс (пункт «Синхронизировать» в меню источника данных), либо через API. Синхронизацию также запускают действия, автоматизации, MCP-сервер портала и элемент процесса [«Источник данных»](../processes/overview/#источник-данных). + +### Запуски синхронизации + +Каждая синхронизация — это запуск со статусом «В очереди», «Выполняется», «Успешно» или «Ошибка». Источники данных одного ресурса синхронизируются по очереди. + +Ручная синхронизация, синхронизация по расписанию, из действия, автоматизации или MCP-сервера присоединяется к запуску, который ещё стоит в очереди. Если источник уже выполняет синхронизацию, следующий запуск ставится в очередь за текущим. Для элемента процесса поведение задаётся в поле [«Если источник уже синхронизируется»](../processes/overview/#источник-данных). + +После нажатия «Синхронизировать» отображается уведомление о постановке синхронизации в очередь. Пока запуск не завершён, на карточке источника данных отображается строка «Текущая синхронизация» с его статусом. Если за выполняющимся запуском уже поставлен следующий, он отображается отдельно в строке «Следующая синхронизация». Статусы на карточках обновляются автоматически. + +Чтобы посмотреть историю запусков, выберите в меню источника данных «Запуски источника данных». Новые запуски отображаются сверху. Для каждого указаны статус, время постановки в очередь, даты старта и завершения, длительность. Текст ошибки отображается во всплывающей подсказке к статусу, а кнопка «Лог синхронизации» открывает лог запуска. + +Кнопка «Запросы» открывает окно «Запросы на синхронизацию». Для каждого запроса указаны время, источник запроса, пользователь, режим обработки занятого источника и «Результат запроса»: «Создал запуск» или «Присоединился к запуску». Из запроса можно перейти к запуску процесса, записи действия или автоматизации, которые запросили синхронизацию. + +Если воркер остановился посреди синхронизации, примерно через две минуты запуск получает статус «Ошибка». Такой запуск автоматически не повторяется. Чтобы синхронизировать источник снова, запросите новый запуск или дождитесь следующего запуска по расписанию. ## Удаление сущностей @@ -197,7 +211,7 @@ metadata: ## Логирование запусков -Для каждого запуска источника данных создаётся запись в базе данных (БД), содержащая полный лог выполнения. Максимальное количество подобных записей регулируется параметром «максимальное количество записей» в конфигурации источника данных. При достижении максимального количества старые записи будут удаляться. +Для каждого запуска источника данных создаётся запись в базе данных (БД), содержащая полный лог выполнения. Максимальное количество подобных записей регулируется параметром «Максимальное количество записей» в конфигурации источника данных. При достижении максимального количества старые записи будут удаляться. Незавершённые запуски и запуски, которых ждёт незавершённый процесс, не удаляются. Параметр модуля `datasources.logging.enabled` позволяет выводить в stdout или скрывать логи синхронизации источников данных. При значении `true` логи выводятся в stdout, при значении `false` (по умолчанию) — не выводятся. Параметр задаётся в ModuleConfig `development-platform` (`spec.settings.datasources.logging.enabled`) или в настройках модуля в веб-интерфейсе Deckhouse Platform. diff --git a/content/documentation/admin/datasources/types.ru.md b/content/documentation/admin/datasources/types.ru.md index 990e6bcf..541a985e 100644 --- a/content/documentation/admin/datasources/types.ru.md +++ b/content/documentation/admin/datasources/types.ru.md @@ -84,7 +84,7 @@ DDP (портал) выполняет GET-запрос по URL: `/api/v2/produc Источник данных типа `GitlabRepositoryActivity` возвращает активность проектов GitLab: число открытых merge request, последний коммит и последний пайплайн ветки по умолчанию. -Источник заполняет показатели карточки микросервиса на главной и используется набором данных «GitLab: активность репозиториев». +Источник можно настроить для записи активности репозиториев в собственные параметры каталога. Для вывода пайплайнов и запросов на слияние в карточке микросервиса на главной используются [слоты виджетов](../home/mapping/#слоты-виджетов). ### Авторизация diff --git a/content/documentation/admin/examples/home-custom-catalog.ru.md b/content/documentation/admin/examples/home-custom-catalog.ru.md index ab5c5cb5..168d4db5 100644 --- a/content/documentation/admin/examples/home-custom-catalog.ru.md +++ b/content/documentation/admin/examples/home-custom-catalog.ru.md @@ -57,27 +57,27 @@ description: Настройка правил маппинга главной DDP ## Заполнение областей -Области заполняются по очереди: связи и параметры роли выбираются из ресурса её родительской роли, поэтому сначала сопоставьте ресурсы. +Добавьте существующие ресурсы в соответствующие области. В таблицах их свойств и связей назначьте значения в поле «Роль на главной». Заполните область «Системы»: -1. В блоке «Ресурс каталога» выберите «Продукты». -1. В блоке «Свойства» выберите `domain` для «Домен системы» и `status` для «Жизненный цикл системы». +1. Нажмите «Добавить ресурс каталога» и выберите «Продукты». +1. В таблице «Свойства ресурса» назначьте параметру `domain` роль «Домен системы», а параметру `status` — «Жизненный цикл системы». Заполните область «Микросервисы»: -1. В блоке «Ресурсы каталога» нажмите «Добавить ресурс» и выберите «Сервисы». -1. В карточке ресурса выберите параметры `lang` для «Язык микросервиса» и `repo_url` для «Репозиторий микросервиса». -1. Выберите связь «Продукт — сервис» для «Содержит микросервис» и связь «Сервис — workload» для «Имеет развёртывание». +1. Нажмите «Добавить ресурс каталога» и выберите «Сервисы». +1. Параметру `lang` назначьте роль «Язык микросервиса», а параметру `repo_url` — «Репозиторий микросервиса». +1. В таблице «Связи ресурса» назначьте связи «Продукт — сервис» роль «Содержит микросервис», а связи «Сервис — workload» — «Имеет развёртывание». Заполните области «Окружения» и «Развёртывания»: -1. В области «Окружения» выберите ресурс «Стенды» и параметры `stand_type` для «Тип окружения» и `base_domain` для «Домен окружения». -1. В области «Развёртывания» выберите ресурс «Workloads», связь «Workload — стенд» для «Развёртывание в окружении» и параметры `replicas` и `image`. +1. В области «Окружения» добавьте ресурс «Стенды». Параметру `stand_type` назначьте роль «Тип окружения», параметру `base_domain` — «Домен окружения». +1. В области «Развёртывания» добавьте ресурс «Workloads». Связи «Workload — стенд» назначьте роль «Развёртывание в окружении», параметру `replicas` — «Реплики развёртывания», параметру `image` — «Тег образа развёртывания». +1. В поле «Пример значений» выберите сущность и проверьте, что строки параметров содержат ожидаемые значения. +1. Нажмите «Сохранить». -Нажмите «Сохранить». - -Если после сохранения изменить ресурс роли, форма очистит зависимые связи и параметры. Проверьте их перед повторным сохранением. +Сопоставления отдельного ресурса можно изменить из каталога: откройте меню ресурса → «Маппинг главной», выберите «Роль ресурса на главной» и назначьте роли его свойствам и связям. Порядок описан [в настройке со страницы ресурса](../home/mapping/#настройка-со-страницы-ресурса). ## Проверка результата diff --git a/content/documentation/admin/examples/home-custom-process.ru.md b/content/documentation/admin/examples/home-custom-process.ru.md index 55ad7dc5..e22c3c3a 100644 --- a/content/documentation/admin/examples/home-custom-process.ru.md +++ b/content/documentation/admin/examples/home-custom-process.ru.md @@ -49,6 +49,7 @@ description: Добавление собственного процесса за Создайте процесс: 1. Создайте процесс с названием «Заказать Redis» и добавьте в него задачу с действием заказа. Порядок создания процесса описан в разделе [«Процессы»](../processes/overview/). +1. В поле «Ресурс» привяжите процесс заказа к ресурсу, сопоставленному роли `system` (в каноничной модели — «Системы»). Главная запускает заказ на сущности выбранной системы. 1. Добавьте параметры процесса: | Идентификатор | Значение по умолчанию | Настройки | @@ -68,6 +69,7 @@ description: Добавление собственного процесса за Создайте процесс «Удалить Redis»: 1. Добавьте задачу с действием, которое вызывает API удаления ресурса и удаляет сущность из каталога после успешного выполнения. Удаление сущности настраивается в разделе действия [«Удаление сущностей»](../actions/overview/#удаление-сущностей). +1. Привяжите процесс удаления к ресурсу «Общие ресурсы» или к ресурсу, сопоставленному роли `shared_resource` в своей модели. 1. Добавьте обязательный параметр `instance_name` со значением по умолчанию `{{ .entity.slug }}` и используйте его в теле запроса. ## Добавление процессов на главную diff --git a/content/documentation/admin/examples/home-quick-start.ru.md b/content/documentation/admin/examples/home-quick-start.ru.md index 569274e8..588a6f88 100644 --- a/content/documentation/admin/examples/home-quick-start.ru.md +++ b/content/documentation/admin/examples/home-quick-start.ru.md @@ -1,7 +1,7 @@ --- title: Быстрая настройка главной weight: 30 -description: Пошаговая настройка главной DDP на новой установке — мастер первоначальной настройки, включение главной, учётные данные, реестр шаблонов, привязка процессов к шаблонам и проверка результата. +description: Пошаговая настройка главной DDP на новой установке — мастер первоначальной настройки, учётные данные, реестр шаблонов, привязка процессов к шаблонам и проверка результата. --- Инструкция описывает настройку главной на новой установке Deckhouse Development Portal (DDP, портал) с каноничной моделью каталога. В результате на главной отображаются окружения и развёртывания кластера, а разработчики создают микросервисы из шаблонов и разворачивают их на окружения. @@ -36,15 +36,15 @@ description: Пошаговая настройка главной DDP на но Если применение набора завершилось ошибкой, исправьте причину и нажмите «Повторить с текущего». -## Включение главной +## Проверка набора маппинга -Главная выключена после установки портала. Включите её: +Проверьте, что мастер создал набор маппинга для разделов каталога: 1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга». 1. Убедитесь, что в таблице есть набор «Главная (по умолчанию)» с включённым переключателем «По умолчанию для главной». -1. Включите переключатель «Показывать главную». +1. Откройте вкладку «Главная» и перейдите из раздела «Рабочие пространства» в нужный раздел каталога. -В верхней панели портала появится вкладка «Главная». +Вкладка «Главная» доступна сразу после установки портала. ## Учётные данные diff --git a/content/documentation/admin/examples/home-widget-slot.ru.md b/content/documentation/admin/examples/home-widget-slot.ru.md index cd359976..589dde87 100644 --- a/content/documentation/admin/examples/home-widget-slot.ru.md +++ b/content/documentation/admin/examples/home-widget-slot.ru.md @@ -14,7 +14,7 @@ description: Вывод виджета GitLab на вкладках «Пайпл - разрешения на создание виджетов и разрешение `update:home-mapping-sets`; - внешний сервис GitLab; -- у сущностей микросервисов — параметр с числовым ID проекта GitLab, сопоставленный роли `microservice_gitlab_project_id`. В каноничной модели каталога это параметр `gitlab_repository_id`, который заполняет процесс создания микросервиса из шаблона или источник данных «GitLab: активность репозиториев». +- у сущностей микросервисов — параметр с числовым ID проекта GitLab, сопоставленный роли `microservice_repository_id`. В каноничной модели каталога это параметр `vcs_repository_id`, который заполняет процесс создания микросервиса из шаблона. Для собственного каталога настройте заполнение параметра вашим процессом или источником данных. Набор данных «GitLab: виджеты» создаёт готовые виджеты для обеих вкладок. Инструкция показывает, как настроить виджет самостоятельно, например для другой системы контроля версий или с другими параметрами. @@ -33,7 +33,7 @@ description: Вывод виджета GitLab на вкладках «Пайпл | `.context.microservice.uuid` | UUID сущности микросервиса | | `.context.microservice.slug` | Идентификатор микросервиса | | `.context.microservice.name` | Название микросервиса | -| `.context.repository.id` | Значение роли `microservice_gitlab_project_id` | +| `.context.repository.id` | Значение роли `microservice_repository_id` | | `.context.repository.url` | Значение роли `microservice_repository` | Контекст передаётся только на вкладках карточки микросервиса. Для дашбордов создайте отдельный виджет с конкретным ID проекта. @@ -58,4 +58,4 @@ description: Вывод виджета GitLab на вкладках «Пайпл На вкладке отображаются пайплайны репозитория выбранного микросервиса. При выборе другого микросервиса виджет показывает пайплайны его репозитория. -Если на вкладке отображается «Раздел пока недоступен», слот виджета не заполнен. Если виджет не показывает данные, проверьте, что у микросервиса заполнен параметр, сопоставленный роли `microservice_gitlab_project_id`. +Если на вкладке отображается «Раздел пока недоступен», слот виджета не заполнен. Если виджет не показывает данные, проверьте, что у микросервиса заполнен параметр, сопоставленный роли `microservice_repository_id`. diff --git a/content/documentation/admin/examples/service-autoupdates.ru.md b/content/documentation/admin/examples/service-autoupdates.ru.md index ccb2d334..b3172c74 100644 --- a/content/documentation/admin/examples/service-autoupdates.ru.md +++ b/content/documentation/admin/examples/service-autoupdates.ru.md @@ -627,8 +627,8 @@ values: {{ .template_values | nindent 4 }} На вкладке «Конфигурация» настройте шаги процесса и их порядок выполнения. Названия задач и действий приведены в качестве примера. -1. Добавьте элемент типа «Задача» с названием «Создать проект в GitLab» и выберите действие «Создать проект в GitLab» для запуска. -1. Добавьте элемент типа «Задача» с названием «Создать репозиторий из шаблона» и выберите действие «Создать репозиторий из шаблона» для запуска. +1. Добавьте элемент типа «Действие» с названием «Создать проект в GitLab» и выберите действие «Создать проект в GitLab» для запуска. +1. Добавьте элемент типа «Действие» с названием «Создать репозиторий из шаблона» и выберите действие «Создать репозиторий из шаблона» для запуска. 1. Добавьте элемент типа «Конец» для завершения процесса. После добавления всех элементов настройте последовательность выполнения: diff --git a/content/documentation/admin/home/mapping.ru.md b/content/documentation/admin/home/mapping.ru.md index 3ee6237a..e8263c01 100644 --- a/content/documentation/admin/home/mapping.ru.md +++ b/content/documentation/admin/home/mapping.ru.md @@ -13,7 +13,6 @@ description: Справочник по наборам маппинга глав На панели над таблицей расположены: -- переключатель «Показывать главную» — включает и выключает главную для всех пользователей; - кнопка «Создать» — открывает форму нового набора; - поле «Поиск» — фильтрует наборы по названию и идентификатору. @@ -36,7 +35,7 @@ description: Справочник по наборам маппинга глав Права на работу с наборами: - `create:home-mapping-sets` — создание наборов; -- `update:home-mapping-sets` — изменение наборов, выбор набора по умолчанию, переключатель «Показывать главную»; +- `update:home-mapping-sets` — изменение наборов, выбор набора по умолчанию, настройка сопоставлений со страницы ресурса; - `delete:home-mapping-sets` — удаление наборов. Для просмотра наборов разрешение не требуется: наборы читает каждая страница главной. @@ -52,40 +51,53 @@ description: Справочник по наборам маппинга глав - «Идентификатор» — стабильный идентификатор набора: от 3 до 64 символов, строчные латинские буквы, цифры и дефис. После создания не меняется; - «По умолчанию для главной» — делает набор набором по умолчанию. Первый созданный набор становится набором по умолчанию автоматически. -На вкладке «Маппинг каталога» правила сгруппированы по областям главной. Каждая область раскрывается отдельно и содержит блоки: +На вкладке «Маппинг каталога» правила сгруппированы по областям главной. В области выберите ресурс каталога, затем назначьте роли его свойствам и связям. Действия, процессы шаблонов и виджеты настраиваются для всей области: | Блок | Назначение | | --- | --- | -| «Ресурс каталога» | Ресурс, на котором строится область | -| «Ресурсы каталога» | Несколько ресурсов области, у каждого свои свойства и связи. Используется в областях «Микросервисы» и «Общие ресурсы» | -| «Связи» | Связи, по которым главная обходит сущности области | -| «Свойства» | Идентификаторы параметров сущностей, которые читает главная | +| «Ресурсы каталога» | Карточки ресурсов выбранной области. Кнопка «Добавить ресурс каталога» добавляет ресурс; нажатие на карточку открывает его настройки | +| «Свойства ресурса» | Параметры выбранного ресурса с типами, примерами значений и полем «Роль на главной» | +| «Связи ресурса» | Связи выбранного ресурса, его роль в каждой связи, примеры и поле «Роль на главной» | +| «Возможности ресурса» | Состояние подключения реестра шаблонов для микросервисов; ссылка «Настройки ресурса» открывает каталог | | «Действия» | Слоты действий области | | «Действия по шаблонам» | Процессы, привязанные к шаблону микросервиса. Только в области «Микросервисы» | | «Виджеты» | Слоты виджетов. Только в области «Микросервисы» | -У каждого поля формы есть подсказка с описанием назначения роли, её действия и места на главной. +У каждой роли есть подсказка с описанием назначения и места использования на главной. Кнопка «Редактор спецификации» открывает весь набор в виде документа JSON. Кнопка «К форме» возвращает к форме. Удаление ключа в тексте спецификации не удаляет значение из формы: очистите значение в форме или замените его в тексте. ### Выбор связей и свойств -Список связей и свойств роли строится по ресурсу её родительской роли. Например, связь `has_deployment` выбирается из связей ресурса роли `microservice`, а свойство `environment_domain` — из параметров ресурса роли `environment`. +Настройка начинается с существующих свойств и связей ресурса. В строке параметра или связи выберите значение в поле «Роль на главной»; неиспользуемые строки оставьте со значением «Не используется». -Пока родительская роль не сопоставлена ресурсу, поле недоступно и отображается подсказка «Сначала настройте маппинг связанной роли ресурса, чтобы выбрать элементы из его каталога». +Для проверки значений выберите сущность в поле «Пример значений». В таблице свойств появятся её значения, в таблице связей — число связанных сущностей. Если сущностей нет, назначение ролей остаётся доступным. -При смене ресурса роли форма очищает связи и свойства, которые зависят от этой роли. -Например, при смене ресурса роли `system` очищаются связи `contains_service` и `contains_shared` во всех ресурсах областей «Микросервисы» и «Общие ресурсы». -Очистка выполняется в форме до сохранения; сохраните набор, чтобы изменения применились. +При добавлении ресурса форма предлагает свободные роли по идентификаторам параметров. Например, `language` сопоставляется с `microservice_language`, а `kind` — с `shared_kind`. Такие значения отмечаются «Предложено»; проверьте их перед сохранением. + +Одну роль свойства можно назначить только одному параметру выбранного ресурса. В списке занятая роль отмечается «Роль уже назначена: {property}». Направление роли связи зависит от того, является выбранный ресурс родителем или потомком. + +Незаполненные роли перечисляются в строке «Не закрыто: {roles}». Раздел продолжает работать, а соответствующие поля сущностей остаются пустыми. Для данных собственного каталога назначайте роли явно: идентификатор параметра сам по себе не заменяет сохранённое сопоставление. ### Несколько ресурсов области В областях «Микросервисы» и «Общие ресурсы» роль можно сопоставить нескольким ресурсам каталога, например микросервисам из разных систем учёта. Для каждого ресурса задаются собственные свойства и связи. -Чтобы добавить ресурс, нажмите «Добавить ресурс» и заполните карточку ресурса. -Связь, родитель которой находится в другой области, например `contains_service` от системы к микросервису, доступна для выбора после того, как сопоставлен ресурс этой области. -При смене ресурса в карточке её свойства и связи очищаются. +Нажмите «Добавить ресурс каталога», выберите ресурс и настройте его строки. Для перехода между ресурсами нажимайте их карточки. Кнопка «Убрать ресурс из роли» удаляет сопоставление выбранного ресурса; сам ресурс каталога сохраняется. + +## Настройка со страницы ресурса + +Роль ресурса и его сопоставления можно изменить непосредственно в каталоге. Для этого требуется `update:home-mapping-sets`: + +1. Откройте страницу ресурса в разделе «Каталог». +1. В меню ресурса выберите «Маппинг главной». +1. В поле «Роль ресурса на главной» выберите роль, например «Микросервис». +1. Назначьте роли в таблицах «Свойства ресурса» и «Связи ресурса», проверьте примеры значений и нажмите «Сохранить». + +Изменения записываются в набор по умолчанию. При смене роли ресурс удаляется из прежней роли и добавляется в выбранную. Очистка поля снимает его участие в главной. + +Действия, процессы по шаблонам и виджеты раздела настраиваются [с главной](#настройка-маппинга-с-главной) или в форме набора. Если набора нет, сначала создайте его в «Администрирование» → «Справочники» → «Правила маппинга». ## Области маппинга @@ -172,32 +184,22 @@ description: Справочник по наборам маппинга глав ### Микросервисы -Роли свойств микросервисов. Значения ролей `microservice_binding_*` записывает процесс создания микросервиса из шаблона; по ним работает [обновление из шаблона](../templates/updates/). +Роли свойств микросервисов сопоставляются параметрам репозитория и языка в вашей модели каталога: | Роль | Название в форме | Назначение | Каноничный параметр | | --- | --- | --- | --- | | `microservice_language` | «Язык микросервиса» | Колонка «Язык», фильтр «Все языки» | `language` | | `microservice_repository` | «Репозиторий микросервиса» | Ссылка на репозиторий; `.context.repository.url` виджетов | `repository` | -| `microservice_gitlab_project_id` | «ID проекта GitLab» | `.context.repository.id` виджетов | `gitlab_repository_id` | -| `microservice_binding_template_id` | «Идентификатор шаблона микросервиса» | Шаблон, из которого создан микросервис. По нему выбираются действия по шаблонам | `template_id` | -| `microservice_binding_template_version` | «Версия шаблона микросервиса» | Текущая версия шаблона в репозитории | `template_version` | -| `microservice_binding_template_source` | «Источник шаблона микросервиса» | Название реестра, из которого получен шаблон | `template_source` | -| `microservice_binding_template_update_policy` | «Политика обновления шаблона» | `manual` или `review-auto` | `template_update_policy` | -| `microservice_binding_template_upgrade_strategy` | «Стратегия обновления шаблона» | Стратегия обновления, заданная для микросервиса | `template_upgrade_strategy` | -| `microservice_binding_template_upgrade_overwrite` | «Пути, перезаписываемые при обновлении» | Список путей для перезаписи, заданный для микросервиса | `template_upgrade_overwrite` | -| `microservice_binding_template_upgrade_add_if_missing` | «Пути, добавляемые при обновлении» | Список добавляемых путей, заданный для микросервиса | `template_upgrade_add_if_missing` | +| `microservice_repository_id` | «Идентификатор репозитория в VCS» | `.context.repository.id` виджетов | `vcs_repository_id` | | `microservice_vcs_provider` | «Провайдер системы контроля версий» | Провайдер репозитория микросервиса | `vcs_provider` | -| `microservice_vcs_external_service_uuid` | «Внешний сервис системы контроля версий» | Внешний сервис GitLab, в котором находится репозиторий | `vcs_external_service_uuid` | -| `microservice_default_branch` | «Ветка по умолчанию микросервиса» | Ветка, в которую создаётся запрос на слияние с обновлением | `default_branch` | -| `microservice_open_mr_count` | «Открытые merge request» | Показатель «Открытые MR» | `open_mr_count` | -| `microservice_last_pipeline_status` | «Статус последнего пайплайна» | Показатель «Последний пайплайн» | `last_pipeline_status` | -| `microservice_last_pipeline_id` | «ID последнего пайплайна» | Номер пайплайна в показателе «Последний пайплайн» | `last_pipeline_id` | -| `microservice_last_pipeline_web_url` | «Ссылка на последний пайплайн» | Ссылка на пайплайн | `last_pipeline_web_url` | -| `microservice_last_commit_sha` | «Хэш последнего коммита» | Строка «Последняя поставка» | `last_commit_sha` | -| `microservice_last_commit_message` | «Сообщение последнего коммита» | Строка «Последняя поставка» | `last_commit_message` | -| `microservice_last_commit_author` | «Автор последнего коммита» | Строка «Последняя поставка» | `last_commit_author` | - -Если роли `microservice_binding_*`, `microservice_vcs_*` или `microservice_default_branch` не сопоставлены, механизм обновления из шаблона использует каноничные идентификаторы параметров из таблицы. +| `microservice_vcs_external_service_uuid` | «Внешний сервис системы контроля версий» | Внешний сервис, через который выполняются операции с репозиторием | `vcs_external_service_uuid` | +| `microservice_default_branch` | «Ветка по умолчанию микросервиса» | Ветка для сверки версии и запроса на слияние с обновлением | `default_branch` | + +Для обновления из шаблона сопоставьте параметры репозитория, провайдера, внешнего сервиса, идентификатора репозитория и ветки. Если роль не сопоставлена, соответствующее значение считается незаданным. + +Сведения о самом шаблоне записываются в [управляемые параметры](../templates/updates/#привязка-микросервиса-к-шаблону) с префиксом `ddp_`. Чтобы портал добавил их в схему ресурса, включите «Реестр шаблонов» на вкладке «Возможности DDP» формы «Редактировать ресурс». + +Управляемые параметры не участвуют в сопоставлении ролей. Их нельзя удалить, изменить их идентификатор или тип либо сделать редактируемыми. Префикс `ddp_` зарезервирован для параметров DDP. Выключение возможности сохраняет уже добавленные параметры. ### Окружения @@ -292,7 +294,7 @@ description: Справочник по наборам маппинга глав Если шаблон, к которому привязаны процессы, больше не доступен в реестре, строка отмечается «нет в реестре». Если реестр пуст, отображается подсказка «В реестре шаблонов нет доступных шаблонов — синхронизируйте реестр, чтобы привязать действия». -Главная определяет шаблон микросервиса по роли свойства `microservice_binding_template_id` в ресурсе этого микросервиса и выбирает процессы следующим образом: +Главная определяет шаблон микросервиса по управляемому параметру `ddp_template_id` сущности этого микросервиса и выбирает процессы следующим образом: - у микросервиса есть шаблон — используется процесс, привязанный к этому шаблону. Если процесс для действия не привязан, действие недоступно с подсказкой, например «Для шаблона {template} не задан процесс развёртывания»; - у микросервиса нет шаблона — для развёртывания и удаления с окружения используются процессы слотов `deploy_microservice` и `delete_microservice` из блока «Действия». @@ -319,7 +321,7 @@ description: Справочник по наборам маппинга глав | `.context.microservice.uuid` | UUID сущности микросервиса | | `.context.microservice.slug` | Идентификатор микросервиса | | `.context.microservice.name` | Название микросервиса | -| `.context.repository.id` | Значение роли `microservice_gitlab_project_id`, пустая строка, если значение не задано | +| `.context.repository.id` | Значение роли `microservice_repository_id`, пустая строка, если значение не задано | | `.context.repository.url` | Значение роли `microservice_repository` | Пример настройки — в разделе [«Виджет на вкладке микросервиса»](../examples/home-widget-slot/). diff --git a/content/documentation/admin/home/overview.ru.md b/content/documentation/admin/home/overview.ru.md index 9786983a..c21bfe6c 100644 --- a/content/documentation/admin/home/overview.ru.md +++ b/content/documentation/admin/home/overview.ru.md @@ -1,11 +1,11 @@ --- title: Обзор weight: 10 -description: Как главная страница DDP получает данные из каталога, какой набор правил маппинга она использует, как её включить и какие права нужны для работы с ней. +description: Как главная страница DDP получает данные из каталога, какой набор правил маппинга она использует, как настроить разделы и какие права нужны для работы с ними. --- -Главная — рабочее пространство разработчиков и владельцев систем в Deckhouse Development Portal (DDP, портал). -На ней собраны команды, системы и их интеграции, микросервисы, окружения, развёртывания, общие ресурсы и потребление ресурсов кластера. +Главная — страница разработчиков и владельцев систем в Deckhouse Development Portal (DDP, портал). +На ней собраны рабочие пространства с AI-агентом и IDE, команды, системы и их интеграции, микросервисы, окружения, развёртывания, общие ресурсы и потребление ресурсов кластера. С главной пользователи создают микросервисы из шаблонов, разворачивают их на окружения, заказывают ресурсы и обновляют микросервисы до новых версий шаблонов. {{< alert level="warning" >}} @@ -16,7 +16,9 @@ description: Как главная страница DDP получает дан ## Принцип работы -Главная не хранит собственных данных. Все объекты, которые она показывает, — это сущности каталога, а все действия — это процессы каталога. +Раздел «Рабочие пространства» показывает рабочие пространства пользователя и управляет их запуском, остановкой, IDE и чатом. Для его работы [подготовьте шаблоны и доступы](../workspaces/overview/). + +Остальные разделы используют сущности и процессы каталога. Какие ресурсы, связи, параметры, процессы и виджеты использовать, задают правила маппинга. Правила маппинга сопоставляют понятиям главной объекты каталога: @@ -66,32 +68,21 @@ flowchart LR Правила маппинга действуют для всех пользователей портала. Выбрать другой набор на главной пользователь не может. -## Включение главной - -Главная выключена после установки портала: вкладка «Главная» скрыта у всех пользователей, а адреса страниц главной перенаправляют в каталог. - -Чтобы включить главную: +## Открытие главной -1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга». -1. Включите переключатель «Показывать главную». +Вкладка «Главная» доступна всем пользователям в верхней панели портала. При переходе на неё открывается раздел «Рабочие пространства». -Переключатель действует сразу для всех пользователей. Для его изменения требуется разрешение `update:home-mapping-sets`. - -При включении главной у пользователей в верхней панели появляется вкладка «Главная», а при переходе на неё открывается раздел «Команды». - -{{< alert level="info" >}} -Баннер «Платформа готова к настройке», из которого запускается мастер первоначальной настройки, отображается на главной. -Пока главная выключена, мастер доступен только в разделе «Администрирование» → «Справочники» → «Наборы данных». -{{< /alert >}} +Пользователи с разрешением `apply:seeds` могут запустить [мастер первоначальной настройки](setup/) из баннера «Платформа готова к настройке» на главной. ## Разделы главной -Разделы главной сгруппированы в боковом меню. Для работы каждого раздела нужны свои роли маппинга; если основная роль раздела не сопоставлена ресурсу каталога, в разделе отображается сообщение «Настройте правила маппинга или примените набор данных «Каноничная архитектура»». +Разделы главной сгруппированы в боковом меню. Раздел «Рабочие пространства» работает независимо от маппинга. Для разделов каталога нужны свои роли маппинга; если основная роль раздела не сопоставлена ресурсу каталога, в разделе отображается сообщение «Настройте правила маппинга или примените набор данных «Каноничная архитектура»». В таблице перечислены разделы, их основные роли ресурсов и слоты действий: | Группа | Раздел | Роли ресурсов | Слоты действий и действия по шаблонам | | --- | --- | --- | --- | +| AI-инструменты | [«Рабочие пространства»](../../user/workspaces/) | Правила маппинга не требуются | — | | Организация | «Команды» | Команды портала; `system`, `microservice` | — | | Архитектура | «Системы» | `system`, `microservice`, `shared_resource`, `deployment`, `environment`, `cluster`, `integration` | — | | Архитектура | «Интеграции» | `system`, `integration` | — | @@ -123,11 +114,11 @@ flowchart LR | `run:actions` на сущность микросервиса | Кнопка «Обновить» в карточке микросервиса | | `read:template-packs` | Галерея шаблонов в разделе «Создать микросервис» и уведомление о новой версии шаблона в карточке микросервиса | | `read:template-registries` | Уведомления о предварительных (prerelease) версиях шаблонов в карточке микросервиса | -| `update:home-mapping-sets` | Переключатели «Показывать главную» и «Настроить маппинг», изменение правил маппинга | +| `update:home-mapping-sets` | Переключатель «Настроить маппинг», изменение правил маппинга, в том числе со страницы ресурса | | `create:home-mapping-sets`, `delete:home-mapping-sets` | Создание и удаление наборов маппинга главной | | `apply:seeds` | Баннер «Платформа готова к настройке» и мастер первоначальной настройки | -Для просмотра главной отдельное разрешение не требуется: вкладка «Главная» доступна всем пользователям, если главная включена. +Для просмотра главной отдельное разрешение не требуется: вкладка «Главная» доступна всем пользователям. Для рабочих пространств действуют [права на пространства и шаблоны](../security/rbac/#рабочие-пространства-и-шаблоны); доступ к разделу «AI» для работы со своими пространствами на главной не требуется. {{< alert level="warning" >}} Пресет роли «Developer» не содержит разрешения `read:entities`. @@ -141,7 +132,6 @@ flowchart LR Чтобы подготовить главную к работе, выполните следующие шаги: 1. Примените наборы данных [мастером первоначальной настройки](setup/) или настройте [правила маппинга](mapping/) для собственной модели каталога. -1. Включите переключатель «Показывать главную». 1. Подключите [реестр шаблонов](../templates/registry/) и привяжите процессы к шаблонам в блоке «Действия по шаблонам». 1. При необходимости добавьте собственные процессы в слоты действий. Требования к таким процессам описаны в разделе [«Процессы главной»](processes/). diff --git a/content/documentation/admin/home/processes.ru.md b/content/documentation/admin/home/processes.ru.md index 360dfa10..21a7323e 100644 --- a/content/documentation/admin/home/processes.ru.md +++ b/content/documentation/admin/home/processes.ru.md @@ -66,6 +66,8 @@ properties: | Создание окружения | `create_environment` | Первое по названию окружение, если окружений нет — первая по названию система | Не передаётся | | Удаление окружения | `delete_environment` | Окружение | Не передаётся | +Процесс должен быть привязан к ресурсу сущности запуска из таблицы. Например, заказ общего ресурса требует привязки к ресурсу систем, удаление — к ресурсу общих ресурсов, а создание окружения — к ресурсам окружений и систем. Для существующих настроек проверьте эти привязки перед запуском; несовпадение ресурса приводит к отказу в запуске. + Ключ `system` передаётся, если на экране выбрана система. Ключ `microservice` при подключении и отключении общего ресурса передаётся, если у развёртывания найден микросервис. При создании окружения сущность запуска не связана с создаваемым окружением: `.entity` в таком процессе указывает на существующее окружение или систему. @@ -101,7 +103,7 @@ properties: | --- | --- | | `.context.template.id` | Идентификатор шаблона микросервиса | | `.context.template.version` | Целевая версия шаблона — последняя доступная | -| `.context.upgrade.strategy` | Стратегия обновления: значение роли `microservice_binding_template_upgrade_strategy` микросервиса, если оно задано, иначе стратегия из пакета шаблона | +| `.context.upgrade.strategy` | Стратегия обновления: значение управляемого параметра `ddp_template_upgrade_strategy` микросервиса, если оно задано, иначе стратегия из пакета шаблона | | `.context.upgrade.overwrite` | Перезаписываемые пути: значение микросервиса или пакета | | `.context.upgrade.add_if_missing` | Добавляемые пути: значение микросервиса или пакета | | `.context.review.title` | Заголовок запроса на слияние: `Upgrade to ` | diff --git a/content/documentation/admin/home/setup.ru.md b/content/documentation/admin/home/setup.ru.md index 2bfd90cf..08c0d152 100644 --- a/content/documentation/admin/home/setup.ru.md +++ b/content/documentation/admin/home/setup.ru.md @@ -30,7 +30,7 @@ description: Мастер первоначальной настройки гла Баннер видят только пользователи с разрешением `apply:seeds`. Баннер скрывается для всех пользователей кнопкой «Скрыть» или автоматически после успешного применения всех выбранных наборов. Чтобы вернуть баннер, включите переключатель «Показывать баннер первоначальной настройки» в разделе «Наборы данных». -Главная выключена после установки портала, поэтому на новой установке баннер не отображается, пока не включён переключатель «Показывать главную». +Главная доступна сразу после установки. Для запуска мастера откройте вкладку «Главная» в верхней панели портала. ## Шаги мастера @@ -90,13 +90,10 @@ description: Мастер первоначальной настройки гла | «Привязка общих ресурсов» | Источник данных «Привязки секретов», процессы «Подключить секреты к приложению» и «Отключить общий ресурс» | «Внешний сервис Kubernetes», «Источник данных Deployments» | | «Управление окружениями» | Процессы «Создать окружение» и «Удалить окружение» | «Внешний сервис Kubernetes», «Источник данных Namespaces» | | «GitLab: группы» | Источник данных групп GitLab для выбора пространства при создании микросервиса | «Внешний сервис GitLab» | -| «GitLab: активность репозиториев» | Источник данных, который заполняет в карточке микросервиса число открытых запросов на слияние, последний пайплайн и последний коммит | «Внешний сервис GitLab», «Все репозитории», «ID групп GitLab», «Включать подгруппы» | | «GitLab: виджеты» | Виджеты «GitLab: пайплайны репозитория» и «GitLab: merge requests репозитория» для вкладок карточки микросервиса | «Внешний сервис GitLab» | | «Deckhouse managed PostgreSQL», «Deckhouse managed Valkey», «Deckhouse managed Kafka» | Действия, процессы заказа и удаления managed-сервиса, источник данных | «Внешний сервис Kubernetes», «Внешний сервис Vault или Stronghold», «Префикс пути Vault» и параметры создания объектов | | «Каноничная архитектура (привязки главной)» | Добавляет процессы и виджеты выбранных наборов в слоты набора маппинга `home-default`. Применяется только мастером | — | -Если в наборе «GitLab: активность репозиториев» выключен параметр «Все репозитории», заполните «ID групп GitLab». - Источники данных Kubernetes собирают только объекты с лейблом `ddp.deckhouse.io/environment` и пропускают неймспейсы `d8-*` и `kube-*`. Какие слоты заполняет набор «Каноничная архитектура (привязки главной)», показано в таблице: @@ -116,7 +113,6 @@ description: Мастер первоначальной настройки гла Мастер не выполняет часть настроек, которые зависят от конкретной установки. Выполните их вручную: -1. Включите главную: «Администрирование» → «Справочники» → «Правила маппинга» → переключатель «Показывать главную». 1. Заполните учётные данные в профиле пользователя: токен сервисного аккаунта Kubernetes, токен Vault, персональный токен и имя пользователя GitLab. Процессы главной выполняют действия с учётными данными пользователя, который их запускает, поэтому учётные данные нужны каждому пользователю, запускающему процессы. 1. Подключите реестр шаблонов и выполните синхронизацию. Порядок описан в разделе [«Реестр шаблонов»](../templates/registry/). diff --git a/content/documentation/admin/install.md b/content/documentation/admin/install.md index 82ff8a91..a8c80ac6 100644 --- a/content/documentation/admin/install.md +++ b/content/documentation/admin/install.md @@ -24,6 +24,8 @@ In the `managed` mode, the module creates PostgreSQL, Valkey (Redis-compatible) | `redis.mode: managed` | `managed-valkey` | | `clickhouse.mode: managed` | `managed-clickhouse` | +With `redis.mode: managed`, the `managed-valkey` module version 0.1.6 or later is required. DDP connects to Valkey as the `ddp` user; the module generates the password and stores it in the `redis-credentials` Secret in the `d8-development-platform` namespace. + For the demo configuration below, enable all three modules using ModuleConfig: ```yaml @@ -170,6 +172,8 @@ spec: mode: internal ``` +If Redis uses ACL users, set the username in the `redis.username` parameter. With an empty value, DDP authenticates with the password only. + ### Full example with external instances Example configuration with connections to external PostgreSQL, Redis and ClickHouse instances: diff --git a/content/documentation/admin/install.ru.md b/content/documentation/admin/install.ru.md index 48a0bd5b..e6690dd6 100644 --- a/content/documentation/admin/install.ru.md +++ b/content/documentation/admin/install.ru.md @@ -24,6 +24,8 @@ ClickHouse хранит исторические данные портала. Ч | `redis.mode: managed` | `managed-valkey` | | `clickhouse.mode: managed` | `managed-clickhouse` | +Для `redis.mode: managed` нужен модуль `managed-valkey` версии 0.1.6 или новее. DDP подключается к Valkey от имени пользователя `ddp`; пароль модуль генерирует и хранит в Secret `redis-credentials` в неймспейсе `d8-development-platform`. + Для демо-конфигурации ниже включите все три модуля с помощью ModuleConfig: ```yaml @@ -170,6 +172,8 @@ spec: mode: internal ``` +Если Redis использует ACL-пользователей, укажите имя пользователя в параметре `redis.username`. С пустым значением DDP подключается только по паролю. + ### Полный пример с внешними экземплярами Пример конфигурации с подключением к внешним экземплярам PostgreSQL, Redis и ClickHouse: diff --git a/content/documentation/admin/overview.ru.md b/content/documentation/admin/overview.ru.md index 9e1699eb..9659cbae 100644 --- a/content/documentation/admin/overview.ru.md +++ b/content/documentation/admin/overview.ru.md @@ -5,3 +5,36 @@ weight: 10 --- Руководство администратора Deckhouse Development Portal (DDP) описывает установку портала и настройку его механизмов: источников данных, действий, процессов, виджетов, проверок статуса и других. Руководство входит в состав эксплуатационной документации продукта. + +Для настройки новых сценариев используйте руководства: + +- [Подготовка рабочих пространств](workspaces/overview/): подключения, сеть, хранилище и лимиты. +- [Создание шаблона](workspaces/templates/): проект OpenTofu, параметры, публикация и активация. +- [Файлы и скрипты](workspaces/files/) и [образы, Ingress и хранение](workspaces/network-storage/): примеры изменения стартового шаблона. +- [AI-агенты](ai-agents/overview/) и [навыки](ai-agents/skills/): инструменты и инструкции агентов. + +## Разделы настройки + +Настройка механизмов портала выполняется в разделах верхней панели: + +| Раздел | Назначение | +| --- | --- | +| «Самообслуживание» | Источники данных, действия, вебхуки, автоматизации, сценарии, дашборды и виджеты | +| «AI» | Агенты, MCP, шаблоны рабочих пространств, навыки и статистика использования | +| «Администрирование» | Команды, пользователи, политики доступа, учётные данные и справочники | + +Для входа в эти разделы требуются соответствующие [разрешения](security/rbac/). + +## Раздел AI + +Раздел «AI» открывается на каталоге агентов. Настройки и журналы сгруппированы в боковом меню: + +| Группа | Пункты меню | +| --- | --- | +| «Агенты» | «Каталог», «Источники агентов», «Шаблоны провайдеров» | +| «MCP» | «Каталог», «MCP-серверы», «MCP-коллекции», «MCP-инструменты» | +| «Рабочие пространства» | «Рабочие пространства», «Шаблоны рабочих пространств», «Источники шаблонов» | +| «Навыки» | «Навыки», «Источники навыков» | +| «Использование» | «Аудит», «Статистика» | + +Каталог агентов показывает источник языковой модели: «Модель DDP» означает работу через AI-провайдера запускающего пользователя, «Модель агента» — собственное подключение внешнего агента к модели. Платформенный агент всегда использует модель DDP. diff --git a/content/documentation/admin/processes/overview.ru.md b/content/documentation/admin/processes/overview.ru.md index 67432912..e796b276 100644 --- a/content/documentation/admin/processes/overview.ru.md +++ b/content/documentation/admin/processes/overview.ru.md @@ -13,12 +13,13 @@ description: Создание и запуск процессов — элеме Процесс состоит из различных типов элементов: * «Начало» — точка входа в процесс. -* «Задача» — выполнение конкретного действия. +* «Действие» — выполнение конкретного действия. * «AI-агент» — отправка задачи AI-агенту и запись его ответа в хранилище процесса. * «Эксклюзивный шлюз» — условное ветвление. * «Параллельный шлюз» — объединение нескольких веток процесса в одну. * «Цикл» — повторение части процесса фиксированное число раз или обход JSON-массива из хранилища. * «Шаблон» — вычисление Go-шаблона и запись результата в хранилище процесса. +* «Источник данных» — синхронизация источников данных и ожидание её окончания. * «Таймер» — пауза до заданного момента времени. * «Примечание» — текстовый блок. * «Ошибка» — немедленная остановка процесса со статусом `Failed`. @@ -52,13 +53,13 @@ description: Создание и запуск процессов — элеме Чтобы добавить элементы на схему: -1. Добавьте элемент, выбрав его тип на панели редактора. Элементы сгруппированы на панели по назначению: «Поток» («Начало», «Конец», «Ошибка»), «Работа» («Задача», «AI-агент», «Шаблон»), «Ветвление» (шлюзы), «Время» («Таймер», «Цикл») и «Разметка» («Примечание»). +1. Добавьте элемент, выбрав его тип на панели редактора. Элементы сгруппированы на панели по назначению: «Поток» («Начало», «Конец», «Ошибка»), «Работа» («Действие», «AI-агент», «Шаблон», «Источник данных»), «Ветвление» (шлюзы), «Время» («Таймер», «Цикл») и «Разметка» («Примечание»). 1. Настройте параметры элемента в боковой панели (действие, условия и др.). 1. Свяжите элементы друг с другом. #### Типы элементов -##### Задача +##### Действие Каждая задача — это запуск конкретного действия, созданного ранее в разделе «Самообслуживание» → «Действия». @@ -83,7 +84,9 @@ description: Создание и запуск процессов — элеме | Поле | Обязательность | Описание | | --- | --- | --- | -| «Агент» | Да | Идентификатор агента. Можно указать Go-шаблон, например `{{ .process.agent_slug }}` | +| «Исполнитель» | Да | «Агент» из каталога или «Рабочее пространство» | +| «Рабочее пространство» | Для исполнителя «Рабочее пространство» | UUID пространства или Go-шаблон, например `{{ .process.workspace_uuid }}` | +| «Агент» | Для исполнителя «Агент» | Идентификатор агента. Можно указать Go-шаблон, например `{{ .process.agent_slug }}` | | «Сообщение агенту» | Да | Go-шаблон сообщения, которое получает агент. Доступны корни `.process`, `.store` и `.context` | | «Ключ результата в хранилище» | Да | Dot-path хранилища процесса, по которому записывается результат, например `agent_result` или `analysis.plan`. По умолчанию — `agent_result` | | «AI-провайдер» | Для агентов, которым модель предоставляет портал | Название AI-провайдера. Обязателен для платформенного агента и внешних агентов с разрешённым прокси моделей DDP | @@ -91,7 +94,9 @@ description: Создание и запуск процессов — элеме AI-провайдер ищется по названию среди провайдеров пользователя, который запустил процесс: провайдер из шаблона с общим токеном подходит всем, кому разрешён шаблон, а личный провайдер — только его владельцу. Если провайдер не задан в элементе, его можно выбрать при запуске процесса. Без провайдера процесс не запускается и возвращает ошибку «Укажите AI-провайдера на каждом локальном agent-шаге перед запуском процесса». -Агент получает инструменты портала из списка «MCP-инструменты» своего подключения. Если список пуст, агент работает без инструментов портала. +Агент получает инструменты назначенных ему MCP-коллекций, которыми может пользоваться инициатор процесса. Без коллекций агент работает без MCP-инструментов. Для запуска требуется право `use:ai-agents` или `use:ai-agent` на выбранного агента. + +В поле «Исполнитель» можно также выбрать «Рабочее пространство». В этом режиме шаг отправляет задание в прикреплённый чат пространства инициатора, привязанного к сущности процесса. ###### Результат агента @@ -182,7 +187,7 @@ AI-провайдер ищется по названию среди провай Ветки эксклюзивного шлюза могут вести к общему элементу, параллельные ветки — к общему элементу «Ошибка». -При сохранении портал также проверяет связность схемы: путь от элемента «Начало» до элемента «Конец», связи циклов и таймеров, настройки элементов «Цикл», «Таймер», «Шаблон» и «AI-агент», например число итераций и часовой пояс. Процесс с ошибкой в схеме не сохраняется, причина указывается в сообщении об ошибке. Запуск процесса, сохранённого с такой ошибкой ранее, отклоняется с той же причиной; сохранить такой процесс можно, только исправив схему. +При сохранении портал также проверяет связность схемы: путь от элемента «Начало» до элемента «Конец», связи циклов и таймеров, настройки элементов «Цикл», «Таймер», «Шаблон», «AI-агент» и «Источник данных», например число итераций и часовой пояс. Процесс с ошибкой в схеме не сохраняется, причина указывается в сообщении об ошибке. Запуск процесса, сохранённого с такой ошибкой ранее, отклоняется с той же причиной; сохранить такой процесс можно, только исправив схему. Параллельный шлюз также может использоваться для разделения веток, если подключается после элементов «Эксклюзивный шлюз» или «Цикл», либо в качестве вспомогательного элемента для повышения читаемости схемы процесса. @@ -241,6 +246,44 @@ AI-провайдер ищется по названию среди провай Примеры и ограничения — в разделе [«Хранилище процесса»](store/#элемент-шаблон). +##### Источник данных + +Элемент «Источник данных» запускает синхронизацию выбранных [источников данных](../datasources/overview/#синхронизация) и продолжает процесс, когда все синхронизации закончатся. + +В конфигурации элемента задаются поля: + +| Поле | Обязательность | Описание | +| --- | --- | --- | +| «Источники данных» | Да | Источники, которые синхронизирует шаг | +| «Если источник уже синхронизируется» | Да | Что делать, если у источника уже есть выполняющийся запуск или запуск в очереди | +| «Таймаут (секунды)» | Нет | Сколько ждать окончания синхронизаций. `0` — без ограничения | + +Шаг запрашивает синхронизацию всех выбранных источников. Источники разных ресурсов могут синхронизироваться одновременно, одного ресурса — по очереди. Если один источник создаёт связи на сущности другого, разместите их в последовательных шагах, чтобы задать порядок синхронизации. + +Варианты поля «Если источник уже синхронизируется»: + +- «Нужны свежие данные» — шаг ждёт синхронизацию, которая начнёт читать источник после того, как процесс дошёл до шага. Шаг присоединяется к запуску в очереди, а если такого запуска нет, создаёт новый. Уже выполняющаяся синхронизация не засчитывается: новый запуск ожидает её окончания. +- «Подождать текущую синхронизацию» — шаг присоединяется к выполняющемуся запуску, а если его нет — к запуску в очереди. Если активных запусков нет, создаётся новый. +- «Завершить с ошибкой» — если хотя бы у одного источника есть выполняющийся запуск или запуск в очереди, шаг сразу получает статус `Failed` и не запрашивает синхронизацию ни одного источника. Если все источники свободны, для каждого создаётся новый запуск. + +Шаг получает статус `Completed`, если все синхронизации завершились успешно, и `Failed`, если хотя бы одна завершилась ошибкой. Даже при ошибке шаг дожидается остальных синхронизаций в пределах своего тайм-аута. + +Удаление источника до начала синхронизации приводит к ошибке. Если синхронизация уже выполняется, она может успешно завершиться с загруженной конфигурацией, и шаг засчитает её результат. + +Дальше процесс идёт так же, как после элемента [«Действие»](#действие): после ошибки он продолжается по исходящим связям, если из шага выходит связь к эксклюзивному шлюзу или связь с условием, иначе ветка процесса на этом шаге завершается. Статус шага проверяется в шлюзе через `{{ .prev_task.status }}`, в хранилище процесса шаг ничего не записывает. + +По истечении тайм-аута шаг получает статус `Timeout`, а синхронизация продолжается. Остановка процесса также не отменяет уже запрошенные синхронизации. + +Приостановка процесса и перезапуск портала не прерывают ожидание: шаг дожидается тех же синхронизаций. Тайм-аут продолжает отсчитываться во время паузы и простоя портала. После возобновления шаг учитывает фактическое время завершения синхронизаций: если они закончились в срок, истёкшее к моменту возобновления время ожидания не приводит к `Timeout`. + +При повторном прохождении шага, например на новой итерации цикла, и при перезапуске процесса шаг снова запрашивает синхронизации с выбранным режимом обработки занятого источника. + +На схеме запуска в боковой панели шага поле «Запуски синхронизации» показывает статус синхронизации каждого источника, а кнопка «Лог синхронизации» открывает её лог. На вкладке «Лог выполнения» шага видно, какую синхронизацию шаг получил для каждого источника и чем она закончилась. + +Для просмотра статусов и логов синхронизации требуется право чтения соответствующего источника данных. Доступ к сущности, для которой запущен процесс, сам по себе не даёт этого права. + +Процесс с шагом без источников или с источником, которого нет, не сохраняется. + ##### Таймер Элемент «Таймер» приостанавливает выполнение процесса до наступления заданного момента времени, после чего активируется следующий элемент. @@ -368,8 +411,8 @@ AI-провайдер ищется по названию среди провай * `Unapproved` — в процессе не осталось другой работы, кроме задач, ожидающих согласования действия. Пока в соседней ветке выполняется шаг «AI-агент» или ожидает таймер, запуск остаётся в статусе `Running` или `Wait`. * `Paused` — выполнение процесса приостановлено. * `Resuming` — запуск восстанавливается после перезапуска портала. -* `Completed` — все ветки процесса завершились, процесс дошёл до элемента «Конец», и каждая ошибка обработана: после задачи или шага «AI-агент», завершившихся ошибкой, или отклонённой задачи ветку продолжил эксклюзивный шлюз или параллельный шлюз, который принимает любой финальный статус. -* `Partially Completed` — процесс дошёл хотя бы до одного элемента «Конец», но часть веток остановилась: на задаче или шаге «AI-агент», которые завершились ошибкой без обработки, на отклонённой задаче без обработки, на шаге, который отменил пользователь, или на параллельном шлюзе, который завершился ошибкой. Статус ставится, когда в запуске не осталось выполняющихся шагов: пока другая ветка работает, например ждёт согласования, запуск остаётся в статусе `Running`, `Unapproved` или `Wait`. +* `Completed` — все ветки процесса завершились, процесс дошёл до элемента «Конец», и каждая ошибка обработана: после задачи, шага «AI-агент» или «Источник данных», завершившихся ошибкой, или отклонённой задачи ветку продолжил эксклюзивный шлюз или параллельный шлюз, который принимает любой финальный статус. +* `Partially Completed` — процесс дошёл хотя бы до одного элемента «Конец», но часть веток остановилась: на задаче, шаге «AI-агент» или «Источник данных», которые завершились ошибкой без обработки, на отклонённой задаче без обработки, на шаге, который отменил пользователь, или на параллельном шлюзе, который завершился ошибкой. Статус ставится, когда в запуске не осталось выполняющихся шагов: пока другая ветка работает, например ждёт согласования, запуск остаётся в статусе `Running`, `Unapproved` или `Wait`. * `Failed` — процесс завершился с ошибкой: ни один элемент «Конец» не достигнут или процесс дошёл до элемента «Ошибка». * `Canceled` — пользователь остановил или отменил запуск. Этот же статус получает запуск, который не дошёл ни до одного элемента «Конец», если его ветки остановились только на шагах, отменённых пользователем. @@ -439,10 +482,10 @@ AI-провайдер ищется по названию среди провай Типовая схема процесса: 1. «Начало» — запуск процесса. -1. «Задача» — создание проекта в GitLab. +1. «Действие» — создание проекта в GitLab. 1. «Эксклюзивный шлюз» — проверка успешности создания. -1. «Задача» (при успехе) — настройка переменных проекта. -1. «Задача» (при ошибке) — отправка уведомления об ошибке. +1. «Действие» (при успехе) — настройка переменных проекта. +1. «Действие» (при ошибке) — отправка уведомления об ошибке. 1. «Конец» — завершение процесса. ### Развёртывание приложения @@ -451,10 +494,10 @@ AI-провайдер ищется по названию среди провай 1. «Начало» — запуск процесса развёртывания. 1. «Параллельный шлюз» — разделение на ветки. -1. «Задача» (ветка 1) — создание неймспейса в Kubernetes. -1. «Задача» (ветка 2) — создание секретов в Vault. +1. «Действие» (ветка 1) — создание неймспейса в Kubernetes. +1. «Действие» (ветка 2) — создание секретов в Vault. 1. «Параллельный шлюз» — ожидание завершения обеих веток. -1. «Задача» — развёртывание приложения. +1. «Действие» — развёртывание приложения. 1. «Конец» — завершение процесса. ## Ограничения diff --git a/content/documentation/admin/security/rbac.ru.md b/content/documentation/admin/security/rbac.ru.md index 40dcc88d..cd429050 100644 --- a/content/documentation/admin/security/rbac.ru.md +++ b/content/documentation/admin/security/rbac.ru.md @@ -113,15 +113,24 @@ MCP: - `read:mcp-tools` — просмотр пользовательских MCP-инструментов. - `edit:mcp-tools` — создание, редактирование и удаление пользовательских MCP-инструментов. -AI-агенты: -- `run:ai-agents` — работа с AI-ассистентом и виджетом «AI-чат», запуск платформенного агента. -- `run:ai-agents-a2a` — запуск платформенного агента в шагах процессов без доступа к AI-ассистенту и виджету «AI-чат». -- `read:ai-agents` — просмотр каталога AI-агентов и источников агентов. -- `edit:ai-agents` — подключение, изменение и удаление внешних агентов и источников агентов, синхронизация источников. -- `read:ai-agent-runs` — просмотр истории своих запусков агентов. -- `cancel:ai-agent-runs` — остановка своих запусков агентов. -- `read:ai-provider-templates` — просмотр шаблонов AI-провайдеров, включая отключённые. -- `edit:ai-provider-templates` — создание, изменение и удаление шаблонов AI-провайдеров. Подробнее — [в документации по AI-агентам](../ai-agents/overview/#разрешения). +AI-агенты и навыки: + +- `use:ai-agents` — использование доступных агентов в чате, виджете и процессе. +- `read:ai-agents`, `edit:ai-agents` — просмотр и управление подключениями и источниками агентов. +- `read:ai-agent-runs`, `cancel:ai-agent-runs` — просмотр и остановка своих запусков. +- `read:ai-provider-templates`, `edit:ai-provider-templates`, `use:ai-provider-templates` — просмотр, управление и использование шаблонов AI-провайдеров. +- `read:agent-skills`, `edit:agent-skills` — просмотр и управление навыками. +- `read:agent-skill-sources`, `edit:agent-skill-sources` — просмотр и управление источниками навыков. +- `read:ai-statistics` — общая статистика использования AI. + +Рабочие пространства: + +- `create:workspaces`, `read:workspaces` — создание и просмотр рабочих пространств. +- `update:workspaces` — запуск, обновление и открытие IDE. +- `cancel:workspaces`, `delete:workspaces` — остановка и удаление. +- `create:workspace-templates`, `read:workspace-templates`, `edit:workspace-templates`, `use:workspace-templates` — создание, просмотр, изменение и использование шаблонов. +- `read:workspace-template-sources`, `edit:workspace-template-sources` — просмотр и управление источниками шаблонов. +- `read:workspace-policy`, `edit:workspace-policy` — просмотр и изменение лимитов установки. Внешние сервисы: @@ -162,7 +171,7 @@ AI-агенты: Правила маппинга главной: - `create:home-mapping-sets` — создание наборов маппинга главной. -- `update:home-mapping-sets` — изменение наборов маппинга главной, выбор набора по умолчанию, включение и выключение главной. Подробнее — [в документации по правилам маппинга](../home/mapping/). +- `update:home-mapping-sets` — изменение наборов маппинга главной, выбор набора по умолчанию и настройка сопоставлений со страницы ресурса. Подробнее — [в документации по правилам маппинга](../home/mapping/). - `delete:home-mapping-sets` — удаление наборов маппинга главной. Шаблоны микросервисов: @@ -220,7 +229,7 @@ AI-агенты: - `view:admin-page` — доступ к разделу «Администрирование». - `view:self-service-page` — доступ к разделу «Самообслуживание». -- `view:ai-page` — доступ к разделу «AI». Для работы с AI-ассистентом также требуется разрешение `run:ai-agents`. +- `view:ai-page` — доступ к разделу «AI». Для работы с AI-ассистентом требуется доступ хотя бы к одному включённому агенту через `use:ai-agents`, `use:ai-agent` или владение при включённом `owner-is-admin`. {{< alert level="info" >}} Без соответствующих `view:` разрешений пользователь не сможет увидеть разделы в навигационном меню, даже если у него есть другие разрешения для работы с объектами в этих разделах. @@ -267,23 +276,44 @@ AI-агенты: #### MCP-коллекции -Для MCP-коллекций: +Для MCP-коллекций действуют разрешения: - `use:mcp-collections` — вызов инструментов коллекции в AI-ассистенте и через MCP-сервер портала. - `edit:role-bindings` — редактирование привязок ролей для коллекции. #### Шаблоны AI-провайдеров -Для шаблонов AI-провайдеров: - -- `use:ai-provider-templates` — использование шаблона с общим токеном: провайдер из шаблона появляется у пользователя без подключения. -- `edit:role-bindings` — редактирование привязок ролей для шаблона. +Для конкретного шаблона используются `read:ai-provider-template`, `edit:ai-provider-template`, `use:ai-provider-template` и `edit:role-bindings`. Глобальное `use:ai-provider-templates` разрешает использование шаблонов на уровне установки. #### AI-агенты -Для AI-агентов: +Для конкретного подключения используются `read:ai-agent`, `edit:ai-agent`, `use:ai-agent` и `edit:role-bindings`. Для источника — `read:ai-agent-source`, `edit:ai-agent-source` и `edit:role-bindings`. + +Использование агента не ограничено владельцем: выдайте `use:ai-agent` нужным пользователям или командам через привязку роли. Владение и участие в команде-владельце предоставляют права при включённой настройке `owner-is-admin`. + +#### Навыки агентов + +Для навыка используются `read:agent-skill`, `edit:agent-skill` и `edit:role-bindings`. Для источника навыков — `read:agent-skill-source`, `edit:agent-skill-source` и `edit:role-bindings`. + +Назначенный агенту навык не выдаёт дополнительных разрешений. Чтение навыка в запуске требует инструмента `curated_get_skill`, доступного через MCP-коллекции агента и запускающего пользователя. -- `edit:role-bindings` — редактирование привязок ролей для агента. +#### Рабочие пространства и шаблоны + +Разрешения можно выдать на отдельный объект: + +| Объект | Разрешения | +| --- | --- | +| Рабочее пространство | `read:workspace`, `update:workspace`, `cancel:workspace`, `delete:workspace`, `edit:role-bindings` | +| Шаблон | `read:workspace-template`, `edit:workspace-template`, `use:workspace-template`, `edit:role-bindings` | +| Источник шаблонов | `read:workspace-template-source`, `edit:workspace-template-source`, `edit:role-bindings` | + +`update:workspace` разрешает запуск, обновление и открытие IDE, `cancel:workspace` — остановку. Повтор операции дополнительно проверяет право на её вид. Создание рабочего пространства всегда требует глобального `create:workspaces` и права использования выбранного шаблона. + +Свои рабочие пространства доступны на главной без `view:ai-page`. Это разрешение требуется для входа в раздел «AI» с его настройками и общей таблицей пространств. + +Прикрепление к чату и выполнение заданий процесса требуют пространства самого пользователя. Для процесса также необходима привязка к его сущности. + +Публиковать порты, менять их уровень доступа и отменять публикацию может владелец с правом обновления рабочего пространства. Для приложений «Только владелец» действует такое же ограничение на открытие. Приложения «Пользователи DDP» доступны любому вошедшему незаблокированному пользователю, «Публично» — без входа; права на карточку рабочего пространства для открытия этих ссылок не требуются. Допустимый уровень публикации портов [ограничивается шаблоном](../../workspaces/apps/#уровни-доступа). Для других объектов (действия, автоматизации, процессы, вебхуки, виджеты, дашборды, внешние сервисы и т. д.): - `read:[object-type]` — просмотр объекта. @@ -528,7 +558,7 @@ AI-агенты: - `read:datasources`, `read:entities`, `read:external-services`. - `read:processes`, `read:resource-relations`, `read:resources`. - `read:seeds`, `read:system-alerts`, `read:template-packs`, `read:trusted-certificates`, `read:webhooks`. - - `read:ai-provider-templates`. + - `read:ai-provider-templates`, `read:agent-skills`, `read:agent-skill-sources`. - `read:widgets`, `read:workflows`. - `read:mcp-collections`, `read:mcp-servers`, `read:mcp-tools`. - `read:audit-logs`, `view:admin-page`, `view:ai-page`, `view:self-service-page`. @@ -544,7 +574,7 @@ AI-агенты: - `update:team-variables`. - Назначение: разработчики, которым нужен доступ к просмотру информации и выполнению действий, но не требуется доступ к созданию, изменению или удалению объектов. Разработчики видят только те сущности, к которым им предоставлен доступ через привязки ролей на уровне ресурсов или сущностей. -Пресет «Developer» не содержит разрешений для AI-агентов. Чтобы разработчики работали с AI-ассистентом, добавьте в роль `run:ai-agents`. +Пресет «Developer» также включает `view:ai-page`, `use:ai-agents`, просмотр агентов, шаблонов AI-провайдеров и MCP, просмотр и остановку своих запусков, чтение журнала MCP-вызовов, `create:workspaces`, `read:workspace-templates` и `use:workspace-templates`. Доступ к своим пространствам предоставляется владением при включённом `owner-is-admin`; глобальные права управления всеми пространствами в пресет не входят. Инструменты MCP и использование AI-провайдеров из шаблонов предоставляются отдельно. ##### Пресет «Platform engineer» @@ -553,8 +583,11 @@ AI-агенты: - Каталог: все разрешения для ресурсов, связей ресурсов и сущностей, включая `update:resources-order`. - Страница «Самообслуживание»: `view:self-service-page` и все разрешения для действий, автоматизаций, дашбордов, источников данных, вебхуков, сценариев, процессов и виджетов, включая `run:actions`, `sync:datasources`, `control:processes`, `run:widget-actions`, `create:page-dashboards` и `delete:page-dashboards`. - `update:team-variables`. - - Страница «AI»: `view:ai-page`, разрешения на работу с AI-агентами, источниками агентов, историей запусков и шаблонами AI-провайдеров, а также `read:mcp-collections`, `edit:mcp-collections`, `read:mcp-servers`, `edit:mcp-servers`, `read:mcp-tools` и `edit:mcp-tools`. -- Назначение: инженеры, которые настраивают портал (процессы, источники данных, дашборды и т. д.). + - Страница «AI»: права из «Developer», управление агентами, источниками агентов и шаблонами AI-провайдеров, использование шаблонов AI-провайдеров и MCP-коллекций, чтение и изменение MCP, навыков и их источников, общая статистика AI, просмотр, запуск, остановка, обновление и удаление рабочих пространств. + +Создание и редактирование шаблонов рабочих пространств, управление их источниками и лимитами установки предоставляются отдельно. Созданные ранее роли не обновляются при изменении пресета: проверьте их фактический состав. + +Пресет предназначен для инженеров, которые настраивают портал. #### Пресеты для процессов diff --git a/content/documentation/admin/templates/updates.ru.md b/content/documentation/admin/templates/updates.ru.md index dcce00f1..4ebf4d9b 100644 --- a/content/documentation/admin/templates/updates.ru.md +++ b/content/documentation/admin/templates/updates.ru.md @@ -13,6 +13,7 @@ description: Как DDP обновляет репозитории микросе - подключён и синхронизирован [реестр шаблонов](registry/); - в правилах маппинга главной для шаблона привязан процесс действия «Обновить микросервис из шаблона»: «Микросервисы» → «[Действия по шаблонам](../home/mapping/#действия-по-шаблонам)». Набор данных «Реестр шаблонов микросервисов» создаёт процесс «Обновить микросервис из шаблона», который можно привязать к любому шаблону; +- в ресурсе микросервисов включён «Реестр шаблонов» на вкладке «Возможности DDP» формы «Редактировать ресурс», а параметры репозитория [сопоставлены ролям главной](../home/mapping/#микросервисы); - микросервис создан из шаблона: в репозитории есть lock-файл `.ddp/template.lock.yaml`, а у сущности микросервиса заполнены параметры привязки к шаблону. ## Привязка микросервиса к шаблону @@ -33,20 +34,31 @@ values: Lock-файл содержит значения параметров, переданные при создании, без значений по умолчанию из схемы. По lock-файлу портал определяет текущую версию шаблона в репозитории и значения параметров для отрисовки новой версии. Не удаляйте и не изменяйте lock-файл вручную: без него репозиторий обновить нельзя. -В сущность микросервиса записываются параметры привязки. В таблице указаны параметры каноничной модели каталога и роли маппинга, через которые портал их находит: +В сущность микросервиса записываются управляемые параметры привязки. При включении «Реестр шаблонов» на вкладке «Возможности DDP» ресурс получает следующие параметры: -| Параметр | Название | Роль маппинга | Значение | -| --- | --- | --- | --- | -| `template_id` | «Идентификатор шаблона» | `microservice_binding_template_id` | Идентификатор шаблона | -| `template_version` | «Версия шаблона» | `microservice_binding_template_version` | Текущая версия шаблона в репозитории | -| `template_source` | «Источник шаблона» | `microservice_binding_template_source` | Название реестра, из которого получен шаблон | -| `template_update_policy` | «Политика обновления шаблона» | `microservice_binding_template_update_policy` | «Вручную» (`manual`) или «Ревью автоматически» (`review-auto`) | -| `template_upgrade_strategy` | «Стратегия обновления шаблона» | `microservice_binding_template_upgrade_strategy` | Стратегия обновления для этого микросервиса | -| `template_upgrade_overwrite` | «Перезаписываемые пути обновления» | `microservice_binding_template_upgrade_overwrite` | Список перезаписываемых путей для этого микросервиса | -| `template_upgrade_add_if_missing` | «Добавляемые пути обновления» | `microservice_binding_template_upgrade_add_if_missing` | Список добавляемых путей для этого микросервиса | -| `default_branch` | — | `microservice_default_branch` | Ветка, в которую создаётся запрос на слияние с обновлением | -| `vcs_provider` | — | `microservice_vcs_provider` | Провайдер системы контроля версий | -| `vcs_external_service_uuid` | «Внешний сервис VCS» | `microservice_vcs_external_service_uuid` | Внешний сервис GitLab, в котором находится репозиторий | +| Параметр | Название | Значение | +| --- | --- | --- | +| `ddp_template_id` | «Идентификатор шаблона» | Идентификатор шаблона | +| `ddp_template_version` | «Версия шаблона» | Текущая версия шаблона в репозитории | +| `ddp_template_source` | «Источник шаблона» | Название реестра, из которого получен шаблон | +| `ddp_template_update_policy` | «Политика обновления шаблона» | «Вручную» (`manual`) или «Ревью автоматически» (`review-auto`) | +| `ddp_template_upgrade_strategy` | «Стратегия обновления шаблона» | Стратегия обновления для этого микросервиса | +| `ddp_template_upgrade_overwrite` | «Перезаписываемые пути обновления» | Список перезаписываемых путей для этого микросервиса | +| `ddp_template_upgrade_add_if_missing` | «Добавляемые пути обновления» | Список добавляемых путей для этого микросервиса | + +Портал читает эти параметры по фиксированным идентификаторам. Назначать им роли маппинга не требуется. Их схему защищает DDP: удалить параметр, изменить его идентификатор или тип либо сделать его редактируемым нельзя. Выключение возможности сохраняет добавленные параметры. + +Параметры репозитория остаются частью вашей модели каталога. Сопоставьте их следующим ролям главной: + +| Роль | Каноничный параметр | Значение | +| --- | --- | --- | +| `microservice_repository` | `repository` | HTTPS-адрес репозитория | +| `microservice_repository_id` | `vcs_repository_id` | Идентификатор репозитория в системе контроля версий | +| `microservice_default_branch` | `default_branch` | Ветка для запроса на слияние с обновлением | +| `microservice_vcs_provider` | `vcs_provider` | Провайдер системы контроля версий | +| `microservice_vcs_external_service_uuid` | `vcs_external_service_uuid` | Внешний сервис для операций с репозиторием | + +Назначьте роли явно в [настройках маппинга ресурса](../home/mapping/#настройка-со-страницы-ресурса). При незаданной роли портал считает соответствующее значение незаполненным. Микросервис привязан к паре «шаблон и реестр»: обновления предлагаются только из версий шаблона того же реестра. diff --git a/content/documentation/admin/widgets/ai/chat.ru.md b/content/documentation/admin/widgets/ai/chat.ru.md index c4e8ed36..51816b96 100644 --- a/content/documentation/admin/widgets/ai/chat.ru.md +++ b/content/documentation/admin/widgets/ai/chat.ru.md @@ -21,20 +21,20 @@ weight: 10 | Название вопроса | Да | Короткая подпись, отображаемая на нижней панели виджета и в чате | | Промпт | Да | Инструкция для модели при нажатии на эту кнопку; допускается использование Go-шаблонизации | -При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должен вызвать агент при подготовке ответа. Агент вызывает только инструменты из списка «MCP-инструменты» своего подключения; платформенному агенту также доступны инструменты MCP-коллекций пользователя. +При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должен вызвать агент при подготовке ответа. Агент получает инструменты назначенных ему MCP-коллекций, которыми может пользоваться запускающий пользователь. Без коллекций агент работает без MCP-инструментов. -Инструмент `get_external_data` не входит в базовый набор платформенного агента. Чтобы использовать его в промпте, [добавьте инструмент](../../ai-agents/platform-agent/#добавление-инструментов) платформенному агенту. +Чтобы платформенный агент вызывал `ddp_curated_get_external_data` по инструкции в промпте, включите `curated_get_external_data` в [MCP-коллекции агента](../../ai-agents/platform-agent/#изменение-инструментов-и-навыков) и предоставьте пользователю доступ к этому инструменту через коллекцию. Пример промпта для быстрого вопроса: ```text -1. Вызови MCP tool get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. +1. Вызови MCP-инструмент ddp_curated_get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. 2. Выведи таблицу с последними 10 пайплайнами. ``` ## Использование виджета -Для работы с виджетом требуется разрешение `run:ai-agents`. Если модель агенту предоставляет портал (платформенный агент или внешний агент с разрешённым прокси моделей DDP), у пользователя должен быть [AI-провайдер](../../../../user/ai-assistant/#подключение-ai-провайдера). +Для работы с виджетом требуется глобальное `use:ai-agents` или объектное `use:ai-agent` на выбранного агента. Если модель агенту предоставляет портал (платформенный агент или внешний агент с разрешённым прокси моделей DDP), у пользователя должен быть [AI-провайдер](../../../../user/ai-assistant/#подключение-ai-провайдера). Для виджетов на странице сущности агент получает UUID сущности в контексте задачи. diff --git a/content/documentation/admin/workspaces/_index.ru.md b/content/documentation/admin/workspaces/_index.ru.md new file mode 100644 index 00000000..2e380591 --- /dev/null +++ b/content/documentation/admin/workspaces/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Рабочие пространства +description: Настройка рабочих пространств, шаблонов, запуска в sandbox и синхронизации из GitLab. +weight: 76 +--- diff --git a/content/documentation/admin/workspaces/apps.ru.md b/content/documentation/admin/workspaces/apps.ru.md new file mode 100644 index 00000000..2d4ee48f --- /dev/null +++ b/content/documentation/admin/workspaces/apps.ru.md @@ -0,0 +1,108 @@ +--- +title: Приложения и публикация портов +description: Приложения шаблона рабочего пространства, веб-терминал, резервирование адресов и уровни доступа к опубликованным портам. +weight: 50 +--- + +Шаблон рабочего пространства может публиковать веб-приложения на отдельных HTTPS-адресах и резервировать адреса для портов, которые владелец откроет из портала. Например, шаблон может предоставлять веб-терминал, а пользователь — временно публиковать сервер разрабатываемого приложения. + +Публикация настраивает адрес и доступ. Само приложение запускается контейнером шаблона, скриптом или пользователем. Шлюз `gate` передаёт HTTP-запросы и WebSocket-соединения на порт приложения по `127.0.0.1` внутри пода. + +## Домены и сеть + +Настройте [DNS, Ingress и TLS](network-storage/#публикация-ide) до публикации шаблона. Для адреса IDE `https://ddp-ws-0a26ad26.example-workspaces.com` используются такие адреса: + +| Назначение | Адрес | +| --- | --- | +| Приложение с идентификатором `terminal` | `https://terminal-ddp-ws-0a26ad26.example-workspaces.com` | +| Первый опубликованный порт | `https://p1-ddp-ws-0a26ad26.example-workspaces.com` | + +Wildcard-запись и сертификат для `*.example-workspaces.com` покрывают IDE, приложения и зарезервированные адреса портов. Стартовый Ingress направляет все эти хосты через `gate`. При изменении Ingress сохраните маршруты и TLS для каждого хоста. + +Домен рабочих пространств должен быть отдельным от родительского домена DDP и Dex, для которого браузер допускает cookie. Например, используйте `example-workspaces.com` при адресе портала `ddp.example.com`. Приложение на `ide.example.com` может установить cookie для `example.com`, поэтому такой вариант не обеспечивает разделение с порталом. + +## Приложения шаблона + +В стартовом `main.tf` список `local.apps` содержит веб-терминал. Для добавления приложения измените этот список, например: + +```hcl +apps = [ + { slug = "terminal", name = "Терминал", port = local.terminal_port, share = "owner" }, + { slug = "preview", name = "Предпросмотр", port = 3000, share = "authenticated" }, +] +``` + +Приложение предпросмотра должно самостоятельно запуститься на порту `3000` в поде. Если сервер проверяет заголовок `Host`, разрешите его внешний хост, например `preview-ddp-ws-0a26ad26.example-workspaces.com`. Для сервера разработки Vite это задаётся через `server.allowedHosts`. + +Поля приложения задают адрес, подпись и доступ: + +| Поле | Требования | +| --- | --- | +| `slug` | Уникальный идентификатор до 32 символов: строчные латинские буквы, цифры и дефис; начало и конец — буква или цифра. `ide` и `p` зарезервированы | +| `name` | Название от 1 до 60 символов | +| `port` | Порт приложения от `1` до `65535` | +| `share` | `owner`, `authenticated` или `public` | +| `icon` | Необязательный HTTPS URL иконки | + +В `outputs.tf` обязателен результат: + +```hcl +output "ddp_apps" { + value = local.apps +} +``` + +Если приложений нет, верните пустой список `[]`. Отсутствующий или некорректный `ddp_apps` завершает операцию применения ошибкой. + +## Уровни доступа + +Уровень задаётся отдельно для каждого приложения и опубликованного порта: + +| Значение шаблона | Название в интерфейсе | Кто открывает | +| --- | --- | --- | +| `owner` | «Только владелец» | Владелец с правом обновлять рабочее пространство, как при открытии IDE | +| `authenticated` | «Пользователи DDP» | Любой вошедший в DDP пользователь, который не заблокирован | +| `public` | «Публично» | Любой посетитель без входа в DDP | + +Для `authenticated` не требуется доступ к карточке рабочего пространства. Пользователь открывает переданную ему ссылку и при необходимости входит в портал. Сессии приложений отделены от сессии IDE. + +В настройках шаблона в блоке «Приложения» задайте «Потолок уровня для публикации портов». Владелец не сможет выбрать уровень выше этого значения. Ограничение относится к портам, публикуемым из интерфейса; уровни приложений в `local.apps` задаёт автор шаблона. + +Веб-терминал и другие приложения с выполнением команд от имени владельца оставляйте с `share = "owner"`. Они получают доступ к файлам и токенам внутри пода. + +## Адреса для публикации портов + +Стартовый шаблон резервирует восемь адресов `p1`–`p8`. Чтобы изменить количество, замените значение в существующем блоке `locals`: + +```hcl +app_slots = 8 +``` + +Допустимо от `0` до `100`; значение `0` отключает публикацию портов из интерфейса. Стартовый проект формирует хосты и правила Ingress на основе этого значения. Результат `ddp_runtime` должен возвращать `app_slots` и порт шлюза `gate_port`: + +```hcl +app_slots = local.app_slots +gate_port = local.gate_port +``` + +Добавьте эти поля в существующий объект `value` результата `ddp_runtime`, а не отдельным `output`. + +Публикация из интерфейса занимает свободный адрес без применения OpenTofu. Освобождение адреса выполняется кнопкой «Отменить публикацию». Если новая версия шаблона уменьшает количество адресов, публикации за пределами нового диапазона перестают открываться и помечаются «Адрес не зарезервирован текущей версией шаблона». Владелец может отменить их и при необходимости опубликовать порт заново в доступный адрес. + +## Веб-терминал стартового шаблона + +Стартовый шаблон запускает `ttyd` из штатного образа IDE в контейнере `terminal` и публикует его как приложение «Терминал» с доступом только владельцу. Терминал использует тот же постоянный том, что IDE и агент. Команды выполняются в контейнере терминала с его собственными ограничениями ресурсов. + +Чтобы изменить ограничения, замените значения `terminal_requests` и `terminal_limits` в `main.tf`. Инструменты, установленные [на постоянный том](tools/), доступны и терминалу, если их пути включены в его окружение. + +## Проверка шаблона + +После изменения проверьте черновик в новом рабочем пространстве: + +1. Дождитесь успешной операции создания и откройте вкладку «Приложения». +1. Откройте «Терминал» и проверьте доступ к рабочей директории. +1. Запустите HTTP-приложение на свободном порту и [опубликуйте его из портала](../../user/workspaces/#публикация-порта). +1. Проверьте адрес, TLS и разрешённый уровень доступа. Для `authenticated` проверьте вход другим пользователем; для `public` — открытие без сессии портала. +1. Отмените публикацию и убедитесь, что приложение больше не открывается по этому адресу. + +После проверки опубликуйте и активируйте версию. Существующие рабочие пространства используют прежний состав приложений до [обновления шаблона](../../user/workspaces/#обновление-шаблона). diff --git a/content/documentation/admin/workspaces/files.ru.md b/content/documentation/admin/workspaces/files.ru.md new file mode 100644 index 00000000..3a78ac8c --- /dev/null +++ b/content/documentation/admin/workspaces/files.ru.md @@ -0,0 +1,125 @@ +--- +title: Файлы и скрипты шаблона +description: Добавление файлов в рабочее пространство, сохранение пользовательских изменений и скрипты первоначальной настройки и запуска. +weight: 30 +--- + +Стартовый [шаблон рабочего пространства](templates/) доставляет файлы из `files/` в рабочую директорию `/workspace/code`. Скрипты из `scripts/` выполняют настройку после доставки файлов. Примеры ниже изменяют существующий стартовый шаблон. + +## Добавление файла в рабочую директорию + +Например, чтобы каждое пространство получало настройки редактора: + +1. Откройте шаблон, вкладку «Файлы», и его черновик. +1. Нажмите «Добавить файл» и укажите путь `files/.vscode/settings.json`. Можно также использовать «Загрузить файлы» для текстовых файлов в UTF-8; проверьте путь каждого загруженного файла. +1. Заполните файл: + + ```json + { + "editor.formatOnSave": true, + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true + } + ``` + +1. Нажмите «Сохранить», опубликуйте и активируйте новую версию. +1. Создайте рабочее пространство из этой версии и откройте IDE. + +В рабочей директории появится `/workspace/code/.vscode/settings.json`. Префикс `files/` в целевой путь не входит. Вложенные директории создаются автоматически. + +По умолчанию файл имеет политику `managed`: при каждом запуске содержимое перезаписывается содержимым версии шаблона. Это подходит для настроек, которыми управляет администратор. Для файлов, которые пользователь будет менять, задайте другую политику. + +## Файл с сохранением пользовательских изменений + +Чтобы выдать исходные инструкции агенту и разрешить владельцу менять их, создайте `files/AGENTS.md` или измените уже существующий файл: + +```markdown +# Project instructions + +Read README.md before changing the project. +Run the tests related to changed files. +Show the test results and changed files in the final response. +``` + +В существующем блоке `locals` файла `main.tf` задайте политику по пути относительно `files/`: + +```hcl +file_policies = { + "AGENTS.md" = "create_if_missing" + ".vscode/settings.json" = "create_if_missing" +} +``` + +Политика `create_if_missing` создаёт файл, только если его ещё нет в рабочей директории. Существующий файл, в том числе полученный из Git, сохраняется. Изменение файла в новой версии шаблона не заменяет пользовательскую копию. + +Политики действуют следующим образом: + +| Политика | При первом запуске | При следующем запуске | +| --- | --- | --- | +| `managed` | Записывает содержимое из шаблона, включая замену существующего файла | Снова записывает содержимое из используемой версии шаблона | +| `create_if_missing` | Создаёт только отсутствующий файл | Сохраняет существующий файл | + +В штатном шаблоне `AGENTS.md` уже имеет политику `create_if_missing`. Для остальных файлов без явной политики используется `managed`. + +## Первоначальная настройка нового тома + +Например, чтобы создать директорию для результатов и выдать начальную конфигурацию приложения: + +1. Добавьте файл `files/config/application.example.json`: + + ```json + { + "listen": "0.0.0.0:8080", + "logLevel": "info" + } + ``` + +1. Добавьте файл `scripts/create.sh`: + + ```bash + #!/usr/bin/env bash + set -euo pipefail + + mkdir -p .local/results + if [ ! -e config/application.json ]; then + cp config/application.example.json config/application.json + fi + ``` + +1. Сохраните файлы, опубликуйте и активируйте версию. +1. Создайте рабочее пространство и проверьте директорию `.local/results` и файл `config/application.json`. + +Скрипт выполняется из рабочей директории после клонирования репозитория, доставки файлов и подготовки навыков. После успешного выполнения на томе сохраняется отметка; повторный запуск на том же томе пропускает `create.sh`. Если скрипт завершится ошибкой, следующая попытка повторит его, поэтому проверяйте существование уже созданных файлов. + +Добавление `create.sh` в новую версию шаблона не повторяет уже успешно выполненную первоначальную настройку существующего тома. Для настройки при каждом запуске используйте `start.sh`. + +## Настройка при каждом запуске + +Чтобы проверять конфигурацию и создавать временные директории после каждого запуска пода, добавьте `scripts/start.sh`: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +mkdir -p .local/cache +test -s config/application.json +printf 'Workspace configuration is ready\n' +``` + +В этом примере сначала добавьте `create.sh` и начальный файл из предыдущего примера. При успешном запуске контейнер `bootstrap` выведет `Workspace configuration is ready`. + +Скрипт выполняется до старта агента и IDE. Команды должны завершаться; не запускайте в нём сервер, который занимает процесс навсегда. Ошибка скрипта препятствует готовности пода и отображается в логе `bootstrap` на вкладке «Диагностика». + +Штатный под работает с UID/GID `10000`, без повышения привилегий и с корневой файловой системой только для чтения. Размещайте рабочие данные и устанавливаемые инструменты на постоянном томе. Пример установки Go и настройки окружения агента и IDE — [в руководстве по инструментам разработки](tools/#установка-go). + +## Применение изменений к существующему пространству + +Чтобы существующее пространство получило новые файлы: + +1. Опубликуйте новую версию шаблона. +1. Остановите рабочее пространство. +1. Обновите его до новой версии и дождитесь успешной операции. +1. Запустите рабочее пространство. +1. Проверьте файлы в IDE и лог контейнера `bootstrap`. + +Для `managed` применится новое содержимое. Для `create_if_missing` сохранится существующий файл. Активация версии шаблона сама по себе не меняет файлы уже созданных пространств. diff --git a/content/documentation/admin/workspaces/network-storage.ru.md b/content/documentation/admin/workspaces/network-storage.ru.md new file mode 100644 index 00000000..8679c0ae --- /dev/null +++ b/content/documentation/admin/workspaces/network-storage.ru.md @@ -0,0 +1,125 @@ +--- +title: Образы, Ingress и хранение +description: Примеры настройки image pull secrets, отдельного домена IDE, Ingress, TLS, cert-manager и постоянного тома рабочего пространства. +weight: 40 +--- + +Настройки образов, публикации IDE и постоянного тома находятся в `main.tf` стартового [шаблона рабочего пространства](templates/). Примеры меняют значения в существующем блоке `locals`; второй блок с теми же именами добавлять не требуется. + +## Образы из закрытого хранилища + +Чтобы под рабочего пространства скачивал закрытые образы, создайте в целевом неймспейсе Secret типа `kubernetes.io/dockerconfigjson`. Например, используя подготовленный Docker config без размещения пароля в командной строке: + +```shell +d8 k -n team-workspaces create secret generic workspace-registry --type=kubernetes.io/dockerconfigjson --from-file=.dockerconfigjson=/secure/path/config.json +``` + +Замените `team-workspaces` на «Namespace» шаблона, а путь — на файл с доступом к нужному хранилищу образов. Учётная запись, выполняющая команду, должна иметь право создавать Secret в этом неймспейсе. + +В `main.tf` замените значение: + +```hcl +image_pull_secrets = ["workspace-registry"] +``` + +Для нескольких хранилищ укажите несколько названий Secrets. Стартовый шаблон добавит их в `imagePullSecrets` пода, включая скачивание образа init-контейнера. + +Сохраните, опубликуйте и активируйте шаблон, затем создайте пространство. В «Диагностике» проверьте, что под скачал образы и контейнеры перешли в готовое состояние. + +### Secrets для Jobs операций + +Jobs OpenTofu и поды рабочих пространств используют отдельные настройки скачивания образов. При установке модулем Jobs работают в `d8-development-platform`; дополнительные Secrets для них задаются в `spec.settings.imagePullSecrets` ModuleConfig: + +```yaml +imagePullSecrets: + - operations-registry +``` + +Secret `operations-registry` должен существовать в `d8-development-platform`. Эта настройка не создаёт Secret в целевом кластере и не заполняет `local.image_pull_secrets` шаблона. Подготовьте оба места, если закрытые образы используются для Jobs и рабочих пространств. + +## Публикация IDE + +IDE каждого рабочего пространства публикуется на собственном HTTPS-хосте. Приложения и опубликованные порты получают соседние хосты, например `terminal-ddp-ws-<суффикс>.example-workspaces.com` и `p1-ddp-ws-<суффикс>.example-workspaces.com`. Для домена `example-workspaces.com` стартовый шаблон создаёт адрес вида `https://ddp-ws-<суффикс>.example-workspaces.com`. + +Домен рабочих пространств должен быть отдельным от родительского домена DDP и Dex, для которого браузер допускает cookie. Например, при портале `ddp.example.com` используйте `example-workspaces.com`; адреса под `ide.example.com` этого разделения не обеспечивают. + +Перед запуском подготовьте wildcard-запись `*.example-workspaces.com`, которая указывает на ingress-контроллер целевого кластера. В `main.tf` задайте: + +```hcl +ide_domain = "example-workspaces.com" +ingress_class = "nginx" +ide_tls_secret = "workspace-ide-tls" +ingress_annotations = { + "nginx.ingress.kubernetes.io/proxy-read-timeout" = "3600" + "nginx.ingress.kubernetes.io/proxy-send-timeout" = "3600" +} +``` + +Замените `nginx` на существующий IngressClass. Значение `null` выбирает класс по умолчанию. Secret `workspace-ide-tls` должен находиться в неймспейсе шаблона и содержать сертификат для `*.example-workspaces.com` с доверенной браузером цепочкой. + +Wildcard-сертификат покрывает IDE, приложения и адреса портов. При изменении правил Ingress сохраните все хосты из `local.app_hosts` и `local.slot_hosts`, их TLS и маршрут через шлюз. Схема адресов описана [в настройке приложений](apps/). + +Аннотации в примере предназначены для ingress-nginx и увеличивают тайм-ауты длительных соединений IDE. Для другого контроллера задайте поддерживаемые им аннотации. + +Созданный Ingress направляет трафик в контейнер проверки доступа `gate`, который пропускает сессию, открытую через портал. Сохраняйте этот маршрут при изменении Ingress. Публикация `code-server` напрямую обходит проверку доступа. + +Если ingress-контроллер уже выдаёт подходящий сертификат по умолчанию, задайте `ide_tls_secret = null`. Проверьте, что браузер доверяет сертификату именно для хоста пространства. + +## Выдача сертификата через cert-manager + +При установленном cert-manager и настроенном ClusterIssuer можно получать сертификат для каждого пространства, включающий хост IDE, хосты приложений и все зарезервированные адреса портов. Замените значения в `main.tf`: + +```hcl +ide_domain = "example-workspaces.com" +ingress_class = "nginx" +ide_tls_secret = "${local.name}-ide-tls" +ingress_annotations = { + "cert-manager.io/cluster-issuer" = "letsencrypt-production" + "nginx.ingress.kubernetes.io/proxy-read-timeout" = "3600" + "nginx.ingress.kubernetes.io/proxy-send-timeout" = "3600" +} +``` + +Замените `letsencrypt-production` на свой ClusterIssuer и обеспечьте условия его проверки домена. После создания пространства дождитесь выдачи сертификата и проверьте открытие IDE через портал. + +Cert-manager может сохранять выпущенный Secret после удаления пространства. Если требуется автоматическое удаление сертификатных Secrets вместе с Certificate, настройте cert-manager с `--enable-certificate-owner-ref`; иначе включите очистку таких Secrets в процедуры обслуживания. + +## Хранение данных + +Стартовый шаблон создаёт постоянный том с режимом `ReadWriteOnce`. Репозиторий находится в `/workspace/code`, состояние агента — в `/workspace/state`; оба пути размещены на этом томе. + +Для выбора существующего StorageClass замените значение в `main.tf`: + +```hcl +storage_class = "fast-ssd" +``` + +Значение `null` использует StorageClass по умолчанию. Размер задаёт переменная `storage_size` в `variables.tf`. Для начального размера `20Gi` и вариантов выбора замените существующий блок: + +```hcl +variable "storage_size" { + description = "Размер тома рабочего пространства" + type = string + default = "20Gi" + + validation { + condition = contains(["20Gi", "50Gi", "100Gi"], var.storage_size) + error_message = "Выберите 20Gi, 50Gi или 100Gi." + } +} +``` + +Новое пространство получит выбранный объём. Расширение существующего PVC зависит от StorageClass и возможностей кластера. Не уменьшайте объём и не меняйте класс существующего тома: операция, которая требует удаления или замены тома, отклоняется порталом. + +Остановка сохраняет том; удаление пространства удаляет его постоянные данные. Учитывайте также политику освобождения томов самого StorageClass. + +## Проверка результата + +После изменения шаблона проверьте черновик в новом рабочем пространстве: + +1. На вкладке «Операции» дождитесь успешного применения OpenTofu. +1. В «Диагностике» проверьте скачивание образов, готовность контейнеров и постоянного тома. +1. Нажмите «Открыть IDE» и проверьте сертификат и работу терминала. +1. Создайте файл в рабочей директории, остановите и снова запустите пространство. Файл должен сохраниться. + +После проверки опубликуйте и активируйте версию. Для существующих пространств примените [обновление версии](../../user/workspaces/#обновление-шаблона). diff --git a/content/documentation/admin/workspaces/overview.ru.md b/content/documentation/admin/workspaces/overview.ru.md new file mode 100644 index 00000000..1fed69fd --- /dev/null +++ b/content/documentation/admin/workspaces/overview.ru.md @@ -0,0 +1,65 @@ +--- +title: Подготовка рабочих пространств +description: Подключения Kubernetes и Git, лимиты, сеть, хранилище и права для рабочих пространств DDP. +weight: 10 +--- + +Рабочие пространства запускают IDE и AI-агента в Kubernetes по шаблону рабочего пространства. Шаблон задаёт объекты в целевом кластере; портал управляет созданием, запуском, остановкой, обновлением и удалением. + +## Подготовка установки + +Для первого запуска подготовьте инфраструктуру и доступы: + +1. Создайте [внешний сервис](../external-services/) Kubernetes и заполните реквизиты доступа к целевому кластеру. Подготовьте целевой неймспейс. +1. Предоставьте реквизитам права на объекты шаблона. Штатный шаблон создаёт StatefulSet, Service, Ingress, PersistentVolumeClaim, ConfigMap и Secret. Диагностика также читает поды, их логи и события; управление пространством изменяет число реплик StatefulSet и подключается к контейнерам. +1. Подготовьте класс хранения для постоянного тома. Штатный шаблон использует `ReadWriteOnce`; класс можно выбрать [в файлах шаблона](network-storage/#хранение-данных). +1. Подготовьте отдельный домен IDE и приложений, wildcard-запись DNS и TLS. Используйте домен, отдельный от родительского домена DDP и Dex, для которого браузер допускает cookie. Адреса должны быть доступны из браузера пользователя. Порядок настройки — [в примерах Ingress и TLS](network-storage/#публикация-ide). +1. Обеспечьте доступ из целевых подов и Jobs операций к HTTPS-адресу портала с доверенным сертификатом. Он используется для состояния OpenTofu, обращения к модели, MCP и проверки доступа в IDE. +1. Если используются закрытые хранилища образов, подготовьте Secrets для скачивания образов [в соответствующих неймспейсах](network-storage/#образы-из-закрытого-хранилища). +1. Для шаблона с репозиторием создайте подключение Git и заполните реквизиты. Пользователям потребуется [AI-провайдер](../../user/ai-assistant/#подключение-ai-провайдера). + +Для запуска рабочего пространства в sandbox на Kata Containers или gVisor [настройте RuntimeClass в шаблоне](sandbox/). + +При установке модулем `development-platform` Jobs операций OpenTofu выполняются в неймспейсе модуля. Под, том и Ingress рабочего пространства создаются в кластере и неймспейсе, выбранных в шаблоне. Эти места могут различаться. + +## Лимиты установки + +До первого создания рабочего пространства сохраните лимиты в разделе «AI» → «Рабочие пространства» → «Шаблоны рабочих пространств», блок «Лимиты установки»: + +| Поле | Назначение | +| --- | --- | +| «Запущенных рабочих пространств на пользователя» | Ограничивает число одновременно запущенных пространств одного владельца | +| «Запущенных рабочих пространств всего» | Ограничивает число одновременно запущенных пространств установки | + +Оба значения — целые числа не меньше единицы. Для изменения требуется `edit:workspace-policy`, для просмотра — `read:workspace-policy`. Без сохранённых лимитов создание недоступно. Остановленные пространства не учитываются в лимите запущенных. + +## Выбор учётных данных + +По умолчанию операции в Kubernetes используют реквизиты владельца рабочего пространства, а клонирование репозитория — его токен Git. Реквизиты заполняются в профиле для соответствующего внешнего сервиса. + +На вкладке «Подключение» шаблона можно отдельно для Kubernetes и Git включить «Использовать сервисную учётную запись» и выбрать «Учётная запись». В этом случае операции используют реквизиты выбранного пользователя. + +Токен Git выбранной учётной записи доступен владельцу внутри рабочего пространства. Выбирайте учётную запись с доступом к тем проектам, с которыми разрешена работа по этому шаблону. + +## Выдача доступа + +Для создания рабочих пространств выдайте пользователю `create:workspaces` и право использовать шаблон: глобальное `use:workspace-templates` или объектное `use:workspace-template`. Для перехода в раздел «AI» требуется `view:ai-page`. + +Просмотр, запуск, остановка и удаление регулируются [разрешениями рабочих пространств](../security/rbac/#рабочие-пространства-и-шаблоны). Владение предоставляет права, когда включена настройка `owner-is-admin`. + +После подготовки [создайте и активируйте шаблон](templates/), затем выполните [пользовательский сценарий создания](../../user/workspaces/#создание-рабочего-пространства). + +## Параметры модуля + +При установке модулем можно переопределить адрес backend и ресурсы Jobs операций. Пример фрагмента `spec.settings` ModuleConfig: + +```yaml +workspaces: + backendUrl: https://ddp.example.com + jobResources: + cpuMillicores: 500 + memoryBytes: 1073741824 + temporaryBytes: 134217728 +``` + +Без переопределения используется HTTPS-адрес портала, `500` millicores CPU, `1` ГиБ памяти и `128` МиБ временного хранилища на Job. Значения CPU и памяти задают requests и limits Jobs. Ресурсы контейнеров самого рабочего пространства задаются в шаблоне. diff --git a/content/documentation/admin/workspaces/sandbox.ru.md b/content/documentation/admin/workspaces/sandbox.ru.md new file mode 100644 index 00000000..93e98246 --- /dev/null +++ b/content/documentation/admin/workspaces/sandbox.ru.md @@ -0,0 +1,133 @@ +--- +title: Запуск в sandbox с Kata или gVisor +description: Настройка RuntimeClass в шаблоне рабочего пространства, выбор Kata Containers или gVisor и проверка запуска в Kubernetes. +weight: 45 +--- + +Рабочее пространство можно запускать в изолированной среде Kata Containers или gVisor. Для этого укажите RuntimeClass в OpenTofu-шаблоне рабочего пространства. Менять код DDP и пересобирать его образы не требуется. + +RuntimeClass применяется ко всему поду: агенту OpenCode, IDE, веб-терминалу, шлюзу `gate` и контейнеру `bootstrap`. В штатном шаблоне они используют общую сеть и постоянный том. + +## Подготовка кластера + +В целевом кластере Kubernetes должны быть настроены Kata Containers или gVisor и соответствующий RuntimeClass. Установка среды выполнения зависит от конфигурации кластера: [инструкция Kata Containers](https://github.com/kata-containers/kata-containers/tree/main/tools/packaging/kata-deploy), [инструкция gVisor](https://gvisor.dev/docs/user_guide/quick_start/kubernetes/). + +Проверьте доступные классы с правами администратора целевого кластера: + +```shell +d8 k --context=workspace-cluster get runtimeclass +``` + +Замените `workspace-cluster` на контекст целевого кластера. Выберите название из `metadata.name` RuntimeClass, например `kata-qemu` или `gvisor`. Название класса и его `handler` могут различаться; в шаблоне указывается название класса. + +Если среда выполнения доступна только на части узлов, настройте `scheduling.nodeSelector` и при необходимости `scheduling.tolerations` в RuntimeClass. Без этих ограничений Kubernetes считает, что класс поддерживается всеми узлами. Дополнительные затраты CPU и памяти задаются в `overhead`. Порядок настройки описан [в документации RuntimeClass](https://kubernetes.io/docs/concepts/containers/runtime-class/). + +Подготовьте также [подключение Kubernetes, сеть и постоянный том](overview/). Проверьте, что выбранная среда выполнения поддерживает используемое хранилище и сетевые подключения рабочего пространства. + +## Указание среды выполнения в шаблоне + +Для запуска на определённом RuntimeClass измените черновик [шаблона рабочего пространства](templates/): + +1. Откройте «AI» → «Рабочие пространства» → «Шаблоны рабочих пространств» и выберите шаблон. +1. На вкладке «Файлы» откройте `main.tf`. +1. Найдите `resource "kubernetes_stateful_set_v1" "runtime"` и добавьте в его блок `spec` → `template` → `spec` поле: + + ```hcl + runtime_class_name = "kata-qemu" + ``` + +1. Замените `kata-qemu` на название выбранного класса. Например, для класса gVisor с названием `gvisor` укажите `runtime_class_name = "gvisor"`. +1. Сохраните черновик и [проверьте запуск](#проверка-запуска). +1. После проверки опубликуйте и активируйте новую версию шаблона. + +Поле находится на уровне пода, рядом с `automount_service_account_token` и `security_context`. Добавлять его в отдельный контейнер или в `ddp_runtime` не требуется. Штатный провайдер Kubernetes поддерживает `runtime_class_name`. + +Для существующего рабочего пространства остановите его, выполните [обновление версии шаблона](../../user/workspaces/#обновление-шаблона) и запустите снова. Публикация версии сама по себе существующие пространства не обновляет. + +## Автоматический выбор доступного класса + +Если один шаблон должен выбирать Kata или gVisor по наличию RuntimeClass, запросите список классов из целевого кластера. Учётной записи [подключения Kubernetes шаблона](overview/#выбор-учётных-данных) потребуется право `list` на `runtimeclasses` в API-группе `node.k8s.io` на уровне кластера. При отсутствии права запрос завершится ошибкой доступа. + +Добавьте в `main.tf` запрос и блок локальных значений: + +```hcl +data "kubernetes_resources" "sandbox_runtime_classes" { + api_version = "node.k8s.io/v1" + kind = "RuntimeClass" +} + +locals { + sandbox_runtime_priority = ["kata-qemu", "kata", "gvisor"] + available_runtime_classes = [ + for runtime_class in data.kubernetes_resources.sandbox_runtime_classes.objects : + runtime_class.metadata.name + ] + matching_sandbox_classes = [ + for name in local.sandbox_runtime_priority : name + if contains(local.available_runtime_classes, name) + ] + sandbox_runtime_class = length(local.matching_sandbox_classes) > 0 ? local.matching_sandbox_classes[0] : null +} +``` + +В `sandbox_runtime_priority` укажите названия классов вашей установки в порядке выбора. Пример выбирает первый существующий класс: сначала `kata-qemu`, затем `kata`, затем `gvisor`. Наличие RuntimeClass проверяет регистрацию класса, но не работоспособность его обработчика на узлах. + +В блоке `spec` → `template` → `spec` StatefulSet используйте выбранное значение вместо фиксированной строки: + +```hcl +runtime_class_name = local.sandbox_runtime_class +``` + +Чтобы отсутствие подходящего класса останавливало применение шаблона, добавьте проверку в существующий блок `lifecycle` этого StatefulSet. Сохраните его настройку `ignore_changes`: + +```hcl +lifecycle { + ignore_changes = [spec[0].replicas] + + precondition { + condition = local.sandbox_runtime_class != null + error_message = "No configured sandbox RuntimeClass is available in the target cluster." + } +} +``` + +При пустом списке совпадений операция завершится указанной ошибкой. Этот пример требует sandbox и не запускает рабочее пространство на среде выполнения кластера по умолчанию. + +Выбор выполняется при создании или обновлении рабочего пространства, когда применяется OpenTofu-шаблон. Обычные остановка и запуск меняют число реплик StatefulSet и используют уже сохранённый класс. Для повторного выбора выполните обновление рабочего пространства. + +## Проверка запуска + +Создайте новое рабочее пространство из черновика, доступного редактору шаблона. Затем проверьте результат: + +1. Дождитесь успешной операции создания и статуса «Работает». +1. Проверьте класс фактически созданного пода: + + ```shell + d8 k --context=workspace-cluster -n workspace-team get pod ddp-ws-0a26ad26-0 -o jsonpath='{.spec.runtimeClassName}{"\n"}' + ``` + + Замените контекст, неймспейс и название пода на значения рабочего пространства. Название пода доступно в его диагностике. Команда должна вывести выбранный класс, например `kata-qemu` или `gvisor`. + +1. Проверьте, что под готов, а в его событиях нет ошибок запуска среды выполнения. Значение `runtimeClassName` само по себе показывает только запрошенный класс. +1. Откройте IDE и веб-терминал, выполните задание агента в чате и проверьте публикацию HTTP-приложения, если она используется. +1. Создайте файл в рабочей директории, остановите и снова запустите рабочее пространство. Проверьте, что файл сохранился и класс пода остался выбранным. + +Работу приложений и инструментов проверяйте на выбранной среде выполнения: поддержка системных вызовов, устройств и операций с файлами зависит от Kata или gVisor и их конфигурации. + +## Устранение ошибок + +При ошибке откройте [диагностику рабочего пространства](../../user/workspaces/#диагностика), логи операции и события пода: + +| Симптом | Что проверить | +| --- | --- | +| Ошибка доступа при чтении RuntimeClass | Право `list` у учётной записи целевого Kubernetes-подключения; применяется только к автоматическому выбору | +| `No configured sandbox RuntimeClass is available in the target cluster.` | Названия в `sandbox_runtime_priority` и наличие соответствующих RuntimeClass | +| Под не создаётся или не запускается после выбора класса | Существование RuntimeClass, настройку его `handler` на узлах и события StatefulSet и пода | +| Под остаётся в состоянии Pending | Ограничения размещения RuntimeClass, taints узлов, доступные CPU и память с учётом `overhead`, подключение постоянного тома | +| Контейнер запускается, но инструмент завершается ошибкой | Логи контейнера и совместимость инструмента с выбранной средой выполнения | + +## Границы настройки + +Шаблон задаёт среду выполнения пода рабочего пространства. Job операции OpenTofu запускается отдельно; его среда выполнения определяется настройками кластера, в котором выполняются Jobs операций. + +RuntimeClass выбирает среду выполнения контейнеров. Для ограничения сетевых соединений настройте NetworkPolicy отдельно; доступ к объектам портала по-прежнему регулируется [ролевой моделью DDP](../security/rbac/#рабочие-пространства-и-шаблоны). diff --git a/content/documentation/admin/workspaces/sources.ru.md b/content/documentation/admin/workspaces/sources.ru.md new file mode 100644 index 00000000..45f524f7 --- /dev/null +++ b/content/documentation/admin/workspaces/sources.ru.md @@ -0,0 +1,83 @@ +--- +title: Шаблоны из GitLab +description: Структура репозитория шаблонов рабочих пространств, настройка источника GitLab, публикация версий и архивирование. +weight: 50 +--- + +Источник шаблонов забирает проекты OpenTofu из GitLab вручную или по расписанию. Изменённые файлы становятся новой опубликованной и сразу активной версией шаблона. Редактирование файлов такого шаблона выполняется в GitLab. + +## Подготовка репозитория + +Разместите каждый шаблон в отдельной непосредственной поддиректории выбранной директории. Например, для пути источника `workspace-templates`: + +```text +workspace-templates/ + go-development/ + versions.tf + main.tf + variables.tf + outputs.tf + files/ + AGENTS.md + scripts/ + start.sh + project-review/ + versions.tf + main.tf + variables.tf + outputs.tf + files/ + AGENTS.md +``` + +Идентификаторы шаблонов в примере — `go-development` и `project-review`. Непосредственная поддиректория должна содержать файл `.tf` в своём корне; вложенные `files/` и `scripts/` входят в тот же шаблон. Каждый проект должен возвращать [обязательные результаты `ddp_runtime` и `ddp_apps`](templates/#связь-с-порталом). + +Чтобы перенести ручной шаблон, разместите в GitLab его пользовательские файлы с теми же относительными путями. Не добавляйте создаваемые порталом `ddp.tf`, `ddp.auto.tfvars.json`, состояние OpenTofu и `.terraform`. + +Задайте в каждом проекте собственные [домен IDE, Ingress, Secrets и хранение](network-storage/). Идентификаторы новых шаблонов должны быть свободны в портале. + +## Создание источника + +Для подключения подготовьте внешний сервис GitLab и реквизиты пользователя с доступом к репозиторию. Затем выполните шаги: + +1. Откройте «AI» → «Рабочие пространства» → «Источники шаблонов» и нажмите «Создать источник». +1. Укажите название, идентификатор, владельца и команду. +1. На вкладке «Репозиторий» выберите «Внешний сервис GitLab», «Пользователь для реквизитов», «Проект», «Ветка или тег» и «Директория с шаблонами». +1. Укажите проект как `group/project` или числовой идентификатор, путь как `workspace-templates`. Для корня репозитория используйте `.`. +1. Выберите «Сервис Kubernetes» и «Namespace» для новых шаблонов этого источника. +1. На вкладке «Синхронизация» задайте «Расписание (cron)» и включите «Включён», если нужна автоматическая синхронизация. +1. Сохраните источник и нажмите «Синхронизировать сейчас». +1. Откройте «История синхронизаций» и проверьте результат по каждой директории. + +Новые шаблоны получают Kubernetes-подключение, неймспейс, владельца и команду источника. У уже созданного шаблона эти настройки меняются отдельно; изменение источника их не перезаписывает. Подключение Git для клонирования пользовательского проекта и навыки настройте в самом шаблоне. Репозиторий источника и репозиторий, с которым работает пользователь, выполняют разные задачи. + +## Обновление версии + +Для публикации изменения отредактируйте файлы в GitLab, создайте коммит в выбранной ветке и запустите синхронизацию либо дождитесь расписания. + +Если файлы директории изменились, портал публикует новую версию с меткой из первых 12 символов SHA коммита и активирует её. Новые пространства создаются из этой версии. Существующие пространства остаются на прежних версиях до ручного обновления. + +Без изменения файлов новая версия не создаётся. Если вручную активирована более ранняя версия шаблона, учитывайте отметку «Активна не последняя версия из репозитория» и проверяйте активную версию после синхронизации. + +Выключенный источник синхронизируется только вручную. Файлы управляемого источником шаблона остаются доступны для просмотра и сравнения в портале. + +## Результаты синхронизации + +История показывает время, статус, коммит и результат для каждой директории: + +| Результат | Значение | +| --- | --- | +| «Создан» | Найдена новая директория, шаблон создан с опубликованной версией | +| «Обновлён» | Файлы изменились, опубликована и активирована новая версия | +| «Без изменений» | Файлы совпадают с уже опубликованными | +| «В архиве» | Директория исчезла из репозитория | +| «Восстановлен» | Директория вернулась после архивирования источником | +| «Пропущен» | Директория не обработана; проверьте указанную причину | + +При конфликте идентификатора с ручным шаблоном или шаблоном другого источника существующий объект не перезаписывается. При ошибке проверьте права на GitLab, проект, ветку, путь, допустимость файлов и результаты `ddp_runtime` и `ddp_apps`, затем повторите синхронизацию. + +## Удаление директории или источника + +Удаление директории из выбранной ветки архивирует соответствующий шаблон. Созданные пространства и опубликованные версии сохраняются; новые пространства из архивного шаблона не создаются. Возвращение директории восстанавливает шаблон, если он был архивирован источником. + +Для удаления источника сначала архивируйте его шаблоны. После удаления источника они остаются архивными ручными шаблонами со своими версиями. Данные существующих пространств не удаляются. diff --git a/content/documentation/admin/workspaces/templates.ru.md b/content/documentation/admin/workspaces/templates.ru.md new file mode 100644 index 00000000..8a1a3e81 --- /dev/null +++ b/content/documentation/admin/workspaces/templates.ru.md @@ -0,0 +1,140 @@ +--- +title: Создание шаблона +description: Создание и изменение шаблона рабочего пространства, параметры формы, публикация, проверка черновика и активация версии. +weight: 20 +--- + +Шаблон рабочего пространства — проект OpenTofu с подключением Kubernetes, настройками Git и набором навыков. Новый ручной шаблон содержит стартовый проект с контейнерами агента, IDE, веб-терминала и проверки доступа, постоянным томом, Service и Ingress. + +## Первый шаблон + +Перед созданием выполните [подготовку рабочих пространств](overview/). Затем настройте ручной шаблон: + +1. Откройте «AI» → «Рабочие пространства» → «Шаблоны рабочих пространств» и нажмите «Создать шаблон». +1. Укажите название и уникальный идентификатор, например `team-development`. +1. На вкладке «Подключение» выберите «Подключение Kubernetes» и «Namespace». При необходимости выберите сервисную учётную запись. +1. Для работы с проектом включите «Инициализировать репозиторием», выберите «Подключение Git», задайте HTTPS URL и ветку. Если проект выбирает пользователь, включите «Разрешить переопределять при создании». Для пространства без Git оставьте инициализацию выключенной. +1. Сохраните шаблон и откройте вкладку «Файлы». +1. В `main.tf` задайте `local.ide_domain`, например `example-workspaces.com`, и проверьте [параметры Ingress, TLS, образов и хранения](network-storage/). Используйте отдельный домен от DDP и Dex. Для запуска пода на Kata Containers или gVisor [укажите RuntimeClass](sandbox/). +1. В настройках шаблона в блоке «Приложения» задайте «Потолок уровня для публикации портов». Состав приложений и количество адресов настраиваются [в файлах шаблона](apps/). +1. Нажмите «Сохранить», затем «Опубликовать v1». +1. На вкладке «Версии» нажмите «Активировать v1». + +Пользователь создаёт новое рабочее пространство из активной версии. Опубликованная версия неизменяема; следующая правка выполняется в черновике и публикуется новой версией. + +## Состав стартового проекта + +Файлы определяют объекты Kubernetes и содержимое рабочей директории: + +| Путь | Назначение | +| --- | --- | +| `versions.tf` | Версия OpenTofu, версия и конфигурация провайдера Kubernetes | +| `main.tf` | StatefulSet, постоянный том, Secrets, ConfigMap, Service, Ingress и настройки доставки файлов | +| `variables.tf` | Пользовательские параметры формы создания | +| `outputs.tf` | Обязательные результаты `ddp_runtime` и `ddp_apps` | +| `files/` | Текстовые файлы для рабочей директории пространства | +| `scripts/create.sh` | Необязательная первоначальная настройка нового тома | +| `scripts/start.sh` | Необязательная настройка при каждом запуске | + +Портал создаёт `ddp.tf` и `ddp.auto.tfvars.json` самостоятельно. Эти пути, директория `.terraform` и имена переменных с префиксом `ddp_` зарезервированы. Добавляйте собственные переменные без этого префикса. + +## Параметры формы создания + +Переменная корневого модуля становится полем формы рабочего пространства. В редакторе откройте `variables.tf` и добавьте переменную: + +```hcl +variable "runtime_memory" { + description = "Память контейнера агента" + type = string + default = "2Gi" + + validation { + condition = contains(["2Gi", "4Gi", "8Gi"], var.runtime_memory) + error_message = "Выберите 2Gi, 4Gi или 8Gi." + } +} +``` + +В штатном шаблоне `runtime_memory` уже существует: замените её блок вместо добавления второго. Значение используется в `local.runtime_resources`. После публикации в форме появится выбор объёма памяти; без изменения пользователь получит `2Gi`. + +Форма поддерживает типы `string`, `number`, `bool` и `list(string)`. `description` становится пояснением поля, `default` — начальным значением. Переменная без `default` обязательна. Проверка `contains([...], var.)` задаёт варианты выбора. Другие условия `validation` проверяются OpenTofu при операции. + +Пример параметра со списком названий Secrets: + +```hcl +variable "registry_secrets" { + description = "Secrets для скачивания образов в целевом неймспейсе" + type = list(string) + default = [] +} +``` + +Чтобы значение влияло на под, замените соответствующую строку существующего блока `locals` в `main.tf`: + +```hcl +image_pull_secrets = var.registry_secrets +``` + +Параметр с `sensitive = true` скрывается в интерфейсе. Реквизиты подключения Git и Kubernetes задавайте через подключения и учётные записи шаблона. + +## Проверка и публикация изменений + +Для проверки до переключения всех новых пространств: + +1. Откройте черновик и измените файлы. +1. Сохраните их. Если черновик изменён другим пользователем, обновите его и повторно внесите свои изменения в актуальную ревизию. +1. Нажмите «Проверить в рабочем пространстве». Черновик доступен пользователям с правом редактирования шаблона; до публикации используются значения параметров по умолчанию. +1. Проверьте результат создания, IDE, файлы и команды в тестовом рабочем пространстве. +1. Опубликуйте версию и сравните её с предыдущей кнопкой «Сравнить». +1. Активируйте нужную версию на вкладке «Версии». + +Активация влияет на последующие создания. Существующие пространства остаются на своих версиях до [явного обновления](../../user/workspaces/#обновление-шаблона). Чтобы вернуть прежний шаблон для новых созданий, активируйте прежнюю опубликованную версию. + +## Связь с порталом + +В шаблоне обязательны `output "ddp_runtime"` и `output "ddp_apps"`. Стартовый проект возвращает: + +```hcl +output "ddp_runtime" { + value = { + statefulset = kubernetes_stateful_set_v1.runtime.metadata[0].name + namespace = var.ddp_namespace + container = "runtime" + engine_port = local.engine_port + ide_container = "ide" + ide_url = local.ide_url + work_directory = local.work_directory + app_slots = local.app_slots + gate_port = local.gate_port + } +} + +output "ddp_apps" { + value = local.apps +} +``` + +Портал использует StatefulSet для запуска и остановки, контейнер агента и его порт для заданий, адрес `ide_url` для открытия IDE. Поля `app_slots` и `gate_port` обязательны; `app_slots = 0` отключает публикацию портов. Результат `ddp_apps` содержит приложения шаблона или пустой список `[]`. + +Сохраняйте соответствие результатов фактически созданным объектам и HTTPS-адресам при изменении шаблона. Для собственных шаблонов добавьте новые поля, результат `ddp_apps` и [маршруты приложений](apps/); отсутствие обязательного результата или поля завершает операцию ошибкой. + +## Навыки и архивирование + +На вкладке «Навыки» выберите [навыки DDP](../ai-agents/skills/) и закреплённую версию либо «Последняя». Набор фиксируется при создании и каждом запуске рабочего пространства. + +Для шаблона с Git переключатель «Разрешить навыки из репозитория» задаёт доступность навыков самой рабочей копии. Если он выключен, выбранные «Скрытые директории навыков» исключаются из рабочей копии при запуске. Это ограничение видимости файлов; прочитать их через Git всё ещё возможно. + +Архивный шаблон сохраняет версии и существующие рабочие пространства, но новые пространства из него создавать нельзя. Для возобновления создания используйте «Вернуть из архива». + +## Ограничения файлов + +При редактировании учитывайте ограничения шаблона: + +| Ограничение | Значение | +| --- | --- | +| Число файлов | До 256 | +| Размер одного файла | До 1 МиБ | +| Содержимое | Текст в UTF-8 | +| Путь | Относительный, без пустых сегментов, `.` и `..` | + +Практические примеры — [доставка файлов и скрипты](files/), [установка Go и других инструментов](tools/), [образы, Ingress и хранение](network-storage/), [приложения и порты](apps/), [синхронизация из GitLab](sources/). diff --git a/content/documentation/admin/workspaces/tools.ru.md b/content/documentation/admin/workspaces/tools.ru.md new file mode 100644 index 00000000..e9904f6c --- /dev/null +++ b/content/documentation/admin/workspaces/tools.ru.md @@ -0,0 +1,137 @@ +--- +title: Инструменты разработки +description: Установка Go в рабочее пространство скриптом шаблона, настройка PATH для агента и IDE, сохранение инструментов при перезапуске. +weight: 35 +--- + +Инструменты разработки можно устанавливать скриптами шаблона на постоянный том рабочего пространства. Агент и IDE используют этот том совместно. Установка в `/workspace/state` сохраняется после остановки и запуска, а файлы проекта остаются в `/workspace/code`. + +Штатные контейнеры работают с UID/GID `10000` и корневой файловой системой только для чтения. Выбирайте дистрибутив инструмента, который можно распаковать в пользовательскую директорию без `sudo`, `apt` или `apk`. + +## Установка Go + +Пример устанавливает Go `1.27.3` на Linux amd64 или arm64. Версия и SHA-256 архивов зафиксированы в скрипте; они опубликованы [на странице загрузок Go](https://go.dev/dl/). + +### Скрипт установки + +Добавьте в черновик шаблона файл `scripts/start.sh` со следующим содержимым. Если файл уже содержит команды настройки, объедините их с примером: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +: "${DDP_STATE_DIR:?}" +go_version="1.27.3" + +case "$(uname -m)" in + x86_64) + go_arch="amd64" + go_checksum="65efbc80fdc1fa2cd2631cad5b481777a68e8725f34e89f50fc6ac714e379b40" + ;; + aarch64|arm64) + go_arch="arm64" + go_checksum="a06e99309dbcbdca1a8ccd2282c3ee146e55930886e26b4f1193269587165f49" + ;; + *) + printf 'Unsupported architecture: %s\n' "$(uname -m)" >&2 + exit 1 + ;; +esac + +toolchains_dir="${DDP_STATE_DIR}/toolchains" +go_directory="${toolchains_dir}/go${go_version}-linux-${go_arch}" +mkdir -p "$toolchains_dir" "${DDP_STATE_DIR}/tools" "${DDP_STATE_DIR}/tmp/go" + +if [ ! -d "$go_directory" ]; then + staging_dir="$(mktemp -d "${toolchains_dir}/.go-install.XXXXXX")" + trap 'rm -rf "$staging_dir"' EXIT + + curl -fsSL --retry 3 --connect-timeout 15 --max-time 300 "https://go.dev/dl/go${go_version}.linux-${go_arch}.tar.gz" -o "${staging_dir}/go.tar.gz" + printf '%s go.tar.gz\n' "$go_checksum" > "${staging_dir}/go.sha256" + (cd "$staging_dir" && sha256sum -c go.sha256) + tar -xzf "${staging_dir}/go.tar.gz" -C "$staging_dir" + mv "${staging_dir}/go" "$go_directory" + + rm -rf "$staging_dir" + trap - EXIT +fi + +ln -sfn "$go_directory" "${DDP_STATE_DIR}/tools/go" +"${DDP_STATE_DIR}/tools/go/bin/go" version +``` + +Скрипт скачивает и проверяет архив только при отсутствии выбранной версии на томе. Распаковка выполняется во временной директории на том же томе; готовая установка переносится в директорию версии. При повторном запуске используется сохранённая копия. + +Ссылка `/workspace/state/tools/go` указывает на выбранную версию. Благодаря этому при обновлении версии путь в `PATH` остаётся прежним. + +Используйте `start.sh`, чтобы пример применялся и к новым, и к уже созданным пространствам после обновления шаблона. `create.sh` пропускается, если первоначальная настройка тома уже успешно выполнялась. + +### Окружение агента и IDE + +В `main.tf` добавьте следующие поля в существующий блок `local.environment`, сохранив остальные поля: + +```hcl +PATH = "${local.state_directory}/tools/go/bin:${local.state_directory}/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" +GOPATH = "${local.state_directory}/go" +GOCACHE = "${local.state_directory}/cache/go-build" +GOTMPDIR = "${local.state_directory}/tmp/go" +CGO_ENABLED = "0" +``` + +Штатный шаблон передаёт `local.environment` контейнеру первоначальной настройки, агенту и IDE. Go и команды, установленные через `go install`, будут доступны во всех этих контейнерах. Кеш сборки и `GOPATH`, включая кеш модулей, располагаются на постоянном томе. `GOTMPDIR` переносит временные файлы компиляции на тот же том, чтобы сборка не занимала ограниченный `/tmp` контейнера. + +Изменение `PATH` через `export` внутри `start.sh` действует только на сам скрипт и его дочерние процессы. Поэтому задавайте переменные в `main.tf`. + +В примере `CGO_ENABLED = "0"` отключает использование C-компилятора. Он подходит для проектов на Go без зависимостей от C; для проектов с CGo также требуются соответствующий компилятор и системные библиотеки. + +### Публикация и проверка + +Для запуска примера поду нужен HTTPS-доступ к `go.dev` и адресу загрузки после перенаправления, обычно `dl.google.com`. Для зависимостей проекта также нужен доступ к выбранному прокси Go-модулей или репозиториям. Если прямой доступ закрыт, разместите тот же архив во внутреннем хранилище и измените URL в скрипте, сохранив проверку SHA-256. + +Чтобы применить пример: + +1. Сохраните `scripts/start.sh` и `main.tf`, опубликуйте версию и активируйте её. +1. Создайте новое рабочее пространство либо остановите существующее, обновите его версию шаблона и снова запустите. +1. В логе контейнера `bootstrap` на вкладке «Диагностика» проверьте успешную проверку архива и строку `go version`. +1. Откройте терминал IDE и проверьте установку: + + ```shell + go version + go env GOPATH GOCACHE GOTMPDIR CGO_ENABLED + command -v go + ``` + +1. Попросите агента в чате выполнить `go version`. Он должен увидеть ту же версию, что и терминал IDE. +1. Остановите и запустите пространство ещё раз. Go должен остаться доступным; повторное скачивание той же версии не требуется. + +### Проверка сборки + +Для проверки компилятора создайте и запустите программу вне директории проекта. Пример не меняет `go.mod` и исходные файлы проекта: + +```shell +mkdir -p /workspace/state/checks/go +cat > /workspace/state/checks/go/hello.go <<'EOF' +package main + +import "fmt" + +func main() { + fmt.Println("Go is ready") +} +EOF +go run /workspace/state/checks/go/hello.go +``` + +Ожидаемый вывод — `Go is ready`. Затем выполните проверки самого проекта, например `go test ./...` из его корневой директории. + +## Обновление версии инструмента + +Для обновления Go измените `go_version` и обе контрольные суммы архивов в `scripts/start.sh`. Возьмите значения [со страницы загрузок Go](https://go.dev/dl/), сохраните и опубликуйте новую версию шаблона. + +Остановите пространство, обновите шаблон и снова запустите. Скрипт установит новую версию в отдельную директорию и переключит ссылку `tools/go`. Прежняя версия останется на томе; её директорию можно удалить из терминала после проверки новой версии. + +## Установка других инструментов + +Для других инструментов используйте ту же последовательность: выберите архив под архитектуру и системные библиотеки контейнера, проверьте его контрольную сумму, распакуйте на постоянный том и добавьте исполняемые файлы в окружение шаблона. + +Совместимость проверяйте отдельно в агенте и IDE. Штатный агент использует Alpine Linux с musl; для него подходят совместимые с musl или статически скомпонованные бинарные файлы. Совпадения архитектуры процессора недостаточно, если инструмент зависит от системных библиотек. diff --git a/content/documentation/product-info/functional.ru.md b/content/documentation/product-info/functional.ru.md index b5c7b4db..bb4a5ff5 100644 --- a/content/documentation/product-info/functional.ru.md +++ b/content/documentation/product-info/functional.ru.md @@ -21,6 +21,10 @@ weight: 10 - создание, обновление и автоматическое удаление временных тестовых окружений; - запуск задач по анализу и поиску уязвимостей в исходном коде и артефактах сборки; - настройка и выполнение комплексных процессов автоматизации с условиями, таймерами, параллельными шагами, триггерами событий и маршрутизацией согласований и подтверждений действий уполномоченными пользователями; +- создание персональных рабочих пространств с IDE и AI-агентом в Kubernetes, сохранением файлов и управлением сроком работы; +- настройка шаблонов рабочих пространств, включая доставку файлов и синхронизацию из GitLab; +- запуск AI-агентов, назначение версий навыков и управление инструментами через MCP-коллекции; +- сбор статистики использования AI по агентам, моделям, пользователям, навыкам и рабочим пространствам; - разграничение прав доступа пользователей и аудит операций. ## Архитектура diff --git a/content/documentation/release-notes/v1.8.0.ru.md b/content/documentation/release-notes/v1.8.0.ru.md index b8b2a636..df7e360f 100644 --- a/content/documentation/release-notes/v1.8.0.ru.md +++ b/content/documentation/release-notes/v1.8.0.ru.md @@ -1,55 +1,52 @@ --- title: v1.8.0 weight: 880 -description: Заметки о выпуске v1.8.0 — новая страница сущности, проверка обязательных параметров в форме сущности, исправления движка процессов и статусов запусков, настраиваемый тайм-аут шагов, разрешения на управление запусками. +description: Рабочие пространства с IDE, AI-агентом и приложениями, новые MCP-инструменты, каталог навыков, статистика AI и синхронизация источников данных в процессах. --- {{< alert level="info" >}} -Выпуск релиза планируется 15.11.2026 +Выпуск релиза планируется 15.11.2026. {{< /alert >}} ## Несовместимые изменения -### Параметры +При обновлении учитывайте изменения проверок и доступа: -- Форма сущности не сохраняется с пустыми [обязательными параметрами](../user/properties/#конфигурация). Через API, источники данных и действия сущность создаётся без проверки обязательности. -- Окна запуска действия, сценария и процесса не запускаются с пустыми обязательными параметрами типов «Users», «Teams» и «Object». +- Для использования AI-агентов применяются `use:ai-agents` и объектное `use:ai-agent` вместо прежних `run:ai-agents` и `run:ai-agents-a2a`. Проверьте [роли и доступ к агентам](../admin/security/rbac/#ai-агенты). +- Привязка микросервиса к шаблону хранится в [управляемых параметрах с префиксом `ddp_`](../admin/templates/updates/#привязка-микросервиса-к-шаблону). Включите «Реестр шаблонов» в возможностях ресурса и явно сопоставьте параметры репозитория ролям главной. +- Прежние списки инструментов агентов и источников не переносятся: назначьте [MCP-коллекции](../user/mcp-management/#связь-с-ai-ассистентом-и-mcp-сервером) заново. Это относится и к встроенным инструментам. +- Форма сущности проверяет [обязательные параметры](../user/properties/#конфигурация); окна запуска также требуют обязательные значения типов Users, Teams и Object. -## Улучшения - -### Каталог +## Новые возможности -- Новая [страница сущности](../user/catalog/#страница-сущности): описание, команда и владелец под заголовком, блоки «Параметры», «Запуск» и «Связи» на вкладке «Обзор». -- В [списке сущностей](../user/catalog/#список-сущностей) появились фильтры по статусу и команде-владельцу. +Добавлены возможности работы с проектами, AI и внешними данными: -### Параметры +- Добавлены [рабочие пространства](../user/workspaces/) с IDE и AI-агентом для работы с проектами: создание из шаблона, редактирование файлов и выполнение заданий из чата. +- [Шаблоны рабочих пространств](../admin/workspaces/templates/) поддерживают пользовательские параметры, файлы и скрипты; версии публикуются вручную или [из GitLab](../admin/workspaces/sources/). +- [Каталог навыков](../admin/ai-agents/skills/) хранит версии инструкций и материалов, поддерживает [импорт из GitLab](../admin/ai-agents/skill-sources/) и установку в IDE. +- [MCP-сервер](../user/mcp-server/) предоставляет инструменты операций API и новые инструменты работы с каталогом. Коллекция может включать отдельные инструменты, серверы и группы портала целиком. +- [Синхронизация внешних MCP-серверов](../user/mcp-management/#автоматическая-синхронизация) поддерживает расписание и сохраняет последний успешный каталог при ошибке. +- [Статистика AI](../user/ai-statistics/) показывает использование агентов, моделей, MCP, навыков и рабочих пространств. +- Элемент процесса [«Источник данных»](../admin/processes/overview/#источник-данных) запускает синхронизацию выбранных источников и продолжает процесс после её окончания. -Элемент параметра типа [«Array»](../user/properties/#array) задаётся текстом или JSON. +## Улучшения -### Процессы +Улучшены каталог, формы и выполнение процессов: -- У задачи, шага «AI-агент» и параллельного шлюза появилось поле «Таймаут (секунды)». Без значения шаг ждёт 60 минут и получает статус `Timeout`. Подробнее — в разделе [«Задача»](../admin/processes/overview/#задача). -- Схема нового процесса настраивается сразу при создании: вкладки «Конфигурация» и «Параметры» доступны до первого сохранения, процесс открывается со схемой «Начало → Конец». +- Главная страница доступна всем пользователям по умолчанию. Настройка скрытия главной страницы удалена. +- Обновлена [страница сущности](../user/catalog/#страница-сущности); в списке доступны фильтры по статусу и команде. +- Для элементов «Действие», «AI-агент» и параллельных шлюзов процессов настраивается [тайм-аут](../admin/processes/overview/#действие). +- Лимит [чатов AI-ассистента](../user/ai-assistant/#чаты) увеличен с 20 до 50 на пользователя. +- Новые [параметры форм](../user/properties/#конфигурация) по умолчанию необязательны; обязательность задаётся при настройке параметра. +- Элемент параметра типа [«Array»](../user/properties/#array) задаётся текстом или JSON. +- Схема нового процесса [настраивается при создании](../admin/processes/overview/#настройка-процесса), до первого сохранения. +- [История синхронизаций источника данных](../admin/datasources/overview/#запуски-синхронизации) показывает статус, время и инициаторов запусков. ## Исправления -### Процессы - -- Запуск выполняется по схеме, с которой начался: правка процесса и завершение других его запусков больше не влияют на идущий запуск, его возобновление и перезапуск. -- Снята нагрузка на CPU и базу данных, пока задача процесса ждёт воркер. -- Итоговый [статус запуска](../admin/processes/overview/#статусы-процесса) определяется по обработке ошибок: обработанная шлюзом ошибка оставляет `Completed`, необработанная даёт `Partially Completed` и в процессе с одним элементом «Конец». `Partially Completed` ставится только после завершения всех веток. -- [Параллельный шлюз](../admin/processes/overview/#параллельный-шлюз), завершившийся ошибкой или по тайм-ауту, отменяет входящие ветки вместе с действиями и запусками AI-агентов; запуск не завершается, пока работает ветка, которую шлюз не дождался. -- Запуск получает `Unapproved`, только когда не осталось другой работы: шаг «AI-агент» или таймер в соседней ветке не останавливаются до согласования. -- [Эксклюзивный шлюз](../admin/processes/overview/#эксклюзивный-шлюз), у которого не выполнилось ни одно условие, не продолжает процесс по ветке с невыполненным условием, а шлюз с несколькими входящими элементами проверяет статус того элемента, после которого процесс дошёл до шлюза. -- Таймер, ожидавший во время приостановки запуска или перезапуска портала, срабатывает после возобновления. Таймер с расписанием «Определённое число каждого месяца» не пропускает месяц без такого числа. -- После перезапуска портала прерванная задача подхватывает результат уже выполненного действия, а не запускает его повторно; задача с потерянным результатом не оставляет запуск в `Running` навсегда. -- Шаг «AI-агент», который не удалось запустить, сразу получает `Failed` с причиной в логе, а не завершает процесс сообщением `process stalled`. -- Действия и запуски AI-агентов останавливаются, когда запуск завершается ошибкой, отменяется или удаляется. -- Кнопка «Возобновить процесс» и подтверждение действия больше не ждут завершения всего запуска; одновременные команды над одним запуском не теряют его прогресс. -- Управлять запуском можно только через сущность, которой он принадлежит: разрешения на одну сущность не дают управлять запусками другой. -- Таймлайн и схема завершённого запуска больше не показывают элементы выполняющимися до отметки «Сейчас». -- Процесс запускается только для сущностей [ресурсов](../admin/processes/overview/#основная-информация), к которым он привязан: запуск для другой сущности через API или MCP-сервер портала отклоняется с ошибкой `422`, автоматическое обновление из шаблона пропускает микросервис, к ресурсу которого процесс обновления не привязан. - -### MCP - -- Инструмент [`get_process_instance`](../user/mcp-server/#get_process_instance) возвращает хранилище процесса. +Исправлены заметные ошибки выполнения: + +- Процессы сохраняют свою схему при редактировании, корректно обрабатывают параллельные ветки, таймеры, подтверждения и [восстановление запусков](../admin/processes/overview/). +- Переключение чатов во время ответа агента больше не смешивает сообщения разных диалогов. +- Записи действий больше не остаются выполняющимися после удаления связанной сущности. +- [MCP-серверы и инструменты](../user/mcp-management/), а также [шаблоны AI-провайдеров](../admin/ai-agents/provider-templates/), созданные выключенными, сохраняют это состояние. diff --git a/content/documentation/user/ai-assistant.ru.md b/content/documentation/user/ai-assistant.ru.md index e36e2e0b..5e321041 100644 --- a/content/documentation/user/ai-assistant.ru.md +++ b/content/documentation/user/ai-assistant.ru.md @@ -1,5 +1,6 @@ --- title: AI-ассистент +description: Подключение AI-провайдера, выбор агента, работа с чатами, инструментами и рабочими пространствами. --- AI-ассистент — чат, встроенный в Deckhouse Development Portal (DDP, портал). Он отвечает на вопросы о портале, анализирует данные каталога и выполняет задачи с помощью инструментов MCP (Model Context Protocol). @@ -7,7 +8,7 @@ AI-ассистент — чат, встроенный в Deckhouse Development На вопросы в AI-ассистенте отвечает [AI-агент](../admin/ai-agents/overview/). По умолчанию выбран платформенный агент, который разворачивается вместе с порталом. Агент обращается к языковой модели через AI-провайдера пользователя. -Для работы с AI-ассистентом требуется глобальное разрешение `run:ai-agents`. +Для работы с AI-ассистентом выберите доступного агента. Если список агентов пуст, обратитесь к администратору портала. ## Подключение AI-провайдера @@ -104,7 +105,7 @@ Authorization: Bearer {{ .token }} Чаты имеют следующие настройки: -1. До 20 чатов на пользователя. При достижении лимита удалите старые чаты через меню «Действия с чатом». +1. До 50 чатов на пользователя. При достижении лимита кнопка «Новый чат» недоступна и отображается пояснение. Удалите ненужный чат через меню «Действия с чатом», чтобы создать новый. Этот же лимит действует при открытии нового чата рабочего пространства. 1. До первого сообщения у чата служебное название. После первого вопроса название подставляется по тексту (можно «Переименовать»). 1. Удаление чата вместе с историей сообщений в нём необратимо. @@ -126,15 +127,52 @@ Authorization: Bearer {{ .token }} ### Инструменты MCP -Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Набор инструментов агента задаёт администратор в поле «MCP-инструменты» подключения агента. -Платформенному агенту в AI-ассистенте также доступны пользовательские инструменты из [MCP-коллекций](../mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. +Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Доступные инструменты настраивает администратор. Агент использует их с правами пользователя; если нужный инструмент недоступен, обратитесь к администратору. Кнопка «Инструменты» в окне ассистента открывает список инструментов с типом (`internal`, `external`, `custom`), числом аргументов и примером запроса. Кнопка «В поле ввода» вставляет пример в поле ввода. Вызовы инструментов отображаются в ответе агента со статусом «Вызывается», «Вызван», «Ошибка» или «Отменён», длительностью, аргументами и текстом ошибки. -- Встроенные инструменты (`internal`) и их параметры описаны в [документации MCP-сервера](../mcp-server/). -- Подключение MCP-серверов, пользовательских MCP-инструментов и настройка коллекций — в разделе [«Управление MCP»](../mcp-management/). +Встроенные инструменты (`internal`) и их параметры описаны [в справочнике MCP-сервера](../mcp-server/). + +### Вопросы о каталоге и процессах + +Если администратор предоставил агенту инструменты работы с каталогом, задавайте вопросы о сущностях, связях и запусках процессов. Например: + +```text +Какие сервисы принадлежат моим командам? Сгруппируй их по языку разработки +и покажи количество в каждой группе. Используй свойства из схемы каталога. +``` + +Для анализа связей укажите исходную сущность и направление интересующей зависимости: + +```text +Покажи родителей сущности payments на три уровня вверх. +Для каждой сущности укажи путь связи и состояние проверок. +``` + +Для диагностики процессов задайте период и ожидаемую детализацию: + +```text +Найди неуспешные запуски процессов за вчера для сущностей моих команд. +Покажи шаг и причину ошибки каждого запуска. +``` + +Если название неоднозначно, уточните ресурс или UUID сущности. Ответ зависит от заполненности каталога и записанных событий процесса. Одна лишь длительность запуска не подтверждает, что процесс завис. + +## Работа с проектом + +Для задач с файлами прикрепите [рабочее пространство](workspaces/) кнопкой «Прикрепить рабочее пространство». В этом режиме отвечает OpenCode пространства; IDE и чат используют одну рабочую копию. Настройки подтверждений и очереди описаны [в руководстве по чату рабочего пространства](workspace-chat/). + +Если агенту из каталога доступны `curated_get_workspace_templates`, `curated_create_workspace`, `curated_get_workspace` и `curated_attach_workspace`, можно попросить его подготовить пространство прямо из чата. Например: + +```text +Создай рабочее пространство из шаблона team-development для https://gitlab.example.com/team/service.git на 8 часов и прикрепи его к этому чату. После запуска добавь тест обработчика /healthz. +``` + +Агент получает параметры шаблона, создаёт пространство с правами пользователя и прикрепляет его после готовности. Попросите администратора выдать нужные инструменты и доступ к шаблону, если сценарий недоступен. + +Кнопка «Моя статистика» открывает [личные показатели использования AI](ai-statistics/). ## Устранение неполадок @@ -144,8 +182,8 @@ Authorization: Bearer {{ .token }} | --- | --- | | «Для вашей учётной записи не настроен AI-провайдер. Добавьте его в настройках профиля.» | У пользователя нет AI-провайдера. Подключите провайдера, как описано в разделе [«Подключение AI-провайдера»](#подключение-ai-провайдера) | | «Выберите AI-провайдера» | Для выбранного агента нужен провайдер. Выберите провайдера в поле «Провайдер» | -| «Недостаточно прав для запуска этого AI-агента» | У пользователя нет разрешения `run:ai-agents` или выбран внешний агент, владельцем которого пользователь не является | +| «Недостаточно прав для запуска этого AI-агента» | Выберите другого доступного агента или обратитесь к администратору портала | | «LLM-провайдер отклонил запрос. Проверьте API-ключи в настройках профиля.» | Провайдер не принял токен. Проверьте токен и заголовки провайдера | | «Превышен лимит запросов к LLM-провайдеру. Попробуйте позже.» | Провайдер ограничил число запросов | -Ошибки вызова внешних агентов описаны в разделе [«Внешние агенты»](../admin/ai-agents/external-agents/#устранение-неполадок). +При ошибке вызова внешнего агента передайте администратору название агента и сообщение об ошибке. diff --git a/content/documentation/user/ai-statistics.ru.md b/content/documentation/user/ai-statistics.ru.md new file mode 100644 index 00000000..3ca636e8 --- /dev/null +++ b/content/documentation/user/ai-statistics.ru.md @@ -0,0 +1,63 @@ +--- +title: Статистика AI +description: Личная и общая статистика использования агентов, моделей, MCP, навыков и рабочих пространств. +weight: 58 +--- + +Статистика показывает использование AI-агентов, моделей, MCP-инструментов, навыков и рабочих пространств. Данные собираются по дням UTC и обновляются раз в час; время последнего успешного обновления указано в «Данные на». + +## Личная статистика + +В AI-ассистенте нажмите «Моя статистика». Диалог показывает только ваши данные и доступен пользователю, которому разрешено пользоваться чатом. + +Выберите период и вкладку с нужными показателями: + +| Вкладка | Что показывает | +| --- | --- | +| «Обзор» | Запуски агентов, вызовы MCP, токены, задания рабочих пространств и активность | +| «Агенты» | Запуски по агентам и типам запуска, результаты и длительность | +| «Модели» | Запросы и входные/выходные токены по моделям и контексту использования | +| «MCP» | Вызовы инструментов и серверов, ошибки и длительность | +| «Рабочие пространства» | Операции, задания, токены, ожидание подтверждений и изменения файлов | +| «Навыки» | Назначение навыков и фактическое чтение агентами | + +Для сравнения доступны периоды «7 дней», «30 дней», «90 дней» и «365 дней». Учитывайте, что недавно выполненная работа появится после следующего обновления агрегатов. + +## Статистика установки + +Общая статистика открывается в «AI» → «Использование» → «Статистика» с разрешением `read:ai-statistics`. Она включает дополнительную вкладку «Пользователи» и выбор собственного периода. + +Чтобы найти источник расхода: + +1. Выберите период. +1. На вкладке «Модели» сравните входные и выходные токены. +1. На вкладке «Пользователи» выберите пользователя, чтобы отфильтровать остальные вкладки по нему. +1. Проверьте «Агенты», «Рабочие пространства» и «MCP» для определения вида работы. + +## Значение показателей + +При интерпретации учитывайте способ подсчёта: + +| Показатель | Значение | +| --- | --- | +| Токены моделей | Учитываются по отчётам использования, полученным от провайдера. «С отчётом об использовании» показывает число запросов с таким отчётом | +| p50 и p95 | Приближённые значения длительности по группам измерений; незавершённые операции в них не входят | +| Навык «Подключён» | Был назначен агенту или рабочему пространству; это не означает, что агент его прочитал | +| Навык «Использован» | Агент прочитал навык через `curated_get_skill` либо инструмент навыков рабочего пространства | +| Навык «нет в каталоге» | Навык удалён или прочитан не из каталога DDP | +| Рабочие пространства у навыка | Сумма по дням пространств с заданиями; одно пространство может учитываться в разные дни | +| «По TTL» | Остановка рабочего пространства по истечении срока работы | + +Статистика использования не заменяет расчёт стоимости у провайдера. Если провайдер не возвращает отчёт о токенах, число запросов и число запросов с отчётом могут различаться. + +## Хранение данных + +При установке модулем срок хранения суточных агрегатов задаётся в ModuleConfig, в `spec.settings.ai.statistics.retentionDays`. По умолчанию — 365 дней. Пример изменения срока: + +```yaml +ai: + statistics: + retentionDays: 180 +``` + +Агрегаты старше срока удаляются раз в час. Срок хранения подробных журналов запусков и MCP-вызовов задаётся отдельно; сохранённая статистика может оставаться после удаления подробных записей. diff --git a/content/documentation/user/home/microservices.ru.md b/content/documentation/user/home/microservices.ru.md index 6120ef4f..cea6d359 100644 --- a/content/documentation/user/home/microservices.ru.md +++ b/content/documentation/user/home/microservices.ru.md @@ -11,7 +11,7 @@ description: Создание микросервиса из шаблона на Мастер создания микросервиса открывается в разделе «Создать микросервис» или кнопкой «Создать микросервис» в разделе «Микросервисы». Мастер состоит из трёх шагов: «Шаблон», «Сервис» и «Параметры». -Для создания микросервиса требуется разрешение `read:template-packs`. Без него отображается сообщение «Недостаточно прав для просмотра галереи шаблонов.». +Если отображается сообщение «Недостаточно прав для просмотра галереи шаблонов.», обратитесь к администратору портала. ### Шаг «Шаблон» @@ -106,7 +106,6 @@ description: Создание микросервиса из шаблона на | Поле | Содержимое | | --- | --- | | «Репозиторий» | Ссылка на репозиторий | -| «Последняя поставка» | Ветка, коммит, сообщение и автор последнего коммита. Если данные ещё не получены, — «Ещё не синхронизировано» | | «Шаблон» | Идентификатор шаблона, из которого создан микросервис, или «Нет» | | «Версия» | Текущая версия шаблона | | «Владелец», «Команда владелец» | Владелец и команда-владелец сущности | @@ -114,7 +113,7 @@ description: Создание микросервиса из шаблона на | «Окружения» | Окружения, кластеры и версии образа на каждом окружении | | «Общие ресурсы» | Общие ресурсы, подключённые к развёртываниям микросервиса | -Ниже отображаются показатели «Открытые MR» и «Последний пайплайн» со статусом и ссылкой на пайплайн. +Данные о пайплайнах и запросах на слияние доступны на соответствующих вкладках, если администратор настроил виджеты. ### Вкладки «Пайплайны» и «MRs» @@ -152,4 +151,4 @@ URL строится по Ingress-ресурсам окружения: хост - обновление уже выполняется — «Процесс обновления шаблона уже выполняется для этого сервиса.»; - для шаблона не настроен процесс обновления — «Для шаблона {template} не задан процесс обновления. Задайте его в правилах маппинга главной, в действиях по шаблонам.». -Если для микросервиса включено автоматическое обновление, портал сам открывает merge request после выхода новой версии шаблона. Настройка автоматического обновления описана в разделе [«Обновление из шаблона»](../../admin/templates/updates/#автоматическое-обновление) руководства администратора. +Если для микросервиса включено автоматическое обновление, портал сам открывает merge request после выхода новой версии шаблона. Проверьте изменения и примите запрос в GitLab. diff --git a/content/documentation/user/home/overview.ru.md b/content/documentation/user/home/overview.ru.md index acf32ad4..6c9b3142 100644 --- a/content/documentation/user/home/overview.ru.md +++ b/content/documentation/user/home/overview.ru.md @@ -4,23 +4,24 @@ weight: 10 description: Главная страница DDP — разделы и навигация, сообщения при отсутствии данных, запуск процессов и отслеживание их выполнения. --- -Главная — рабочее пространство разработчиков и владельцев систем. На главной собраны команды, системы и их интеграции, микросервисы, окружения, развёртывания и общие ресурсы. +Главная — страница разработчиков и владельцев систем. На главной собраны рабочие пространства с AI-агентом и IDE, команды, системы и их интеграции, микросервисы, окружения, развёртывания и общие ресурсы. С главной создаются микросервисы из шаблонов, микросервисы разворачиваются на окружения, заказываются ресурсы и создаются окружения. {{< alert level="warning" >}} Главная — функциональность на стадии Preview. Состав разделов и их поведение могут измениться в следующих выпусках без сохранения обратной совместимости. {{< /alert >}} -Главная открывается вкладкой «Главная» в верхней панели портала. Если вкладки нет, главная выключена администратором портала; при переходе по адресу страницы главной открывается каталог. +Главная открывается вкладкой «Главная» в верхней панели портала и доступна всем пользователям. Первым открывается раздел «Рабочие пространства». -Главная показывает данные каталога. Какие ресурсы каталога отображаются на главной и какие процессы запускаются её кнопками, задаёт администратор портала в [правилах маппинга](../../admin/home/mapping/). +Раздел «Рабочие пространства» показывает ваши рабочие пространства. В остальных разделах собраны данные каталога: команды, системы, микросервисы и окружения. ## Разделы -Разделы главной сгруппированы в боковом меню. Группа раскрывается нажатием на стрелку, нажатие на название группы открывает её первый раздел. При открытии главной открывается раздел «Команды». +Разделы главной сгруппированы в боковом меню. Группа раскрывается нажатием на стрелку, нажатие на название группы открывает её первый раздел. При открытии главной открывается раздел «Рабочие пространства». | Группа | Раздел | Назначение | | --- | --- | --- | +| «AI-инструменты» | [«Рабочие пространства»](../workspaces/) | Ваши рабочие пространства, создание из шаблона, IDE и чат агента | | «Организация» | [«Команды»](teams/) | Команды портала, их участники, системы и микросервисы | | «Архитектура» | [«Системы»](architecture/#системы) | Системы по доменам, их зависимости, микросервисы, общие ресурсы и окружения | | «Архитектура» | [«Интеграции»](architecture/#интеграции) | Интеграции между системами | @@ -42,11 +43,11 @@ description: Главная страница DDP — разделы и нави | Сообщение | Причина | | --- | --- | -| «Настройте правила маппинга или примените набор данных «Каноничная архитектура»» | Ресурс для раздела не настроен в правилах маппинга, не удалось загрузить сущности или у вас нет прав на просмотр сущностей этого ресурса | +| «Настройте правила маппинга или примените набор данных «Каноничная архитектура»» | Данные раздела не настроены или недоступны. Обратитесь к администратору портала | | «Сущностей пока нет. Создайте их в каталоге или синхронизируйте через datasource.» | Ресурс настроен, но в нём нет сущностей | | «Раздел пока недоступен» | Раздел находится в разработке, или для вкладки не настроен виджет | -Если сообщение о правилах маппинга отображается только у вас, запросите у администратора портала доступ к сущностям ресурса. +Если ожидаемые данные не отображаются, сообщите администратору, какой раздел вы открыли и какое сообщение видите. ## Запуск процессов @@ -85,15 +86,3 @@ description: Главная страница DDP — разделы и нави Итог выполнения процесса — успех или ошибка — отображается в панели «Мои активности» на вкладке «Процессы». Панель открывается значком часов в верхней панели портала; пока у вас выполняются процессы, значок заменяется индикатором. После завершения процесса раздел загружает данные заново. Если объект создаётся синхронизацией источника данных, он появляется на главной после следующей синхронизации. - -## Первоначальная настройка - -Пользователи с разрешением `apply:seeds` видят в верхней части главной баннер «Платформа готова к настройке». Кнопка «Запустить» открывает мастер первоначальной настройки, кнопка «Скрыть» скрывает баннер для всех пользователей. - -Мастер описан в разделе [«Первоначальная настройка»](../../admin/home/setup/) руководства администратора. - -## Настройка маппинга с главной - -Пользователи с разрешением `update:home-mapping-sets` видят в нижней части бокового меню переключатель «Настроить маппинг». Когда переключатель включён, рядом с разделами появляется значок настройки правил маппинга раздела. - -Порядок настройки описан в разделе [«Правила маппинга»](../../admin/home/mapping/#настройка-маппинга-с-главной). diff --git a/content/documentation/user/home/teams.ru.md b/content/documentation/user/home/teams.ru.md index 34b4296e..564215d8 100644 --- a/content/documentation/user/home/teams.ru.md +++ b/content/documentation/user/home/teams.ru.md @@ -4,7 +4,7 @@ weight: 20 description: Раздел главной DDP «Команды» — показатели команд, карта команд и профиль команды с её системами и микросервисами. --- -Раздел «Команды» показывает команды портала, их участников и системы и микросервисы, которыми владеют команды. Раздел открывается при переходе на главную. +Раздел «Команды» показывает команды портала, их участников и системы и микросервисы, которыми владеют команды. Чтобы открыть раздел, перейдите в «Главная» → «Организация» → «Команды». Команды и их участники задаются в разделе «Администрирование». Подробнее — в разделе [«Команды и пользователи»](../teams-users/). Системы и микросервисы команды определяются по полю «Команда владелец» их сущностей в каталоге. diff --git a/content/documentation/user/interface.ru.md b/content/documentation/user/interface.ru.md index 6be3c4cc..25a64bb1 100644 --- a/content/documentation/user/interface.ru.md +++ b/content/documentation/user/interface.ru.md @@ -1,21 +1,19 @@ --- title: Интерфейс +description: Разделы DDP, верхняя панель и поиск сущностей каталога. weight: 20 --- -Интерфейс Deckhouse Development Portal (DDP, портал) состоит из следующих разделов: +Интерфейс Deckhouse Development Portal (DDP, портал) объединяет разделы для работы с проектами: -- «Главная» — рабочее пространство разработчиков: команды, системы, микросервисы, окружения, развёртывание и заказ ресурсов. Вкладка отображается, если главная включена администратором. Подробнее — в разделе [«Главная»](home/overview/). +- «Главная» — страница разработчика: рабочие пространства с AI-агентом и IDE, команды, системы, микросервисы, окружения, развёртывание и заказ ресурсов. Подробнее — в разделе [«Главная»](home/overview/). - «Каталог» — сервисный каталог для просмотра ресурсов, сущностей и связей, а также для запуска действий и сценариев. -- «Самообслуживание» — раздел для настройки источников данных, действий, вебхуков, автоматизаций, сценариев, дашбордов и виджетов. Доступ к разделу может быть ограничен ролевой моделью. -- «AI» — раздел для настройки MCP-серверов, пользовательских инструментов и коллекций инструментов. Подробнее — в разделе [«Управление MCP»](mcp-management/). Доступ к разделу может быть ограничен ролевой моделью. -- «Администрирование» — раздел для управления командами, пользователями, политиками доступа и учётными данными. Доступ к разделу может быть ограничен ролевой моделью. ## Верхняя панель В правой части верхней панели портала расположены кнопки: -- «AI-ассистент» — открывает окно [AI-ассистента](ai-assistant/#работа-с-ai-ассистентом); +- «AI-ассистент» — открывает окно [AI-ассистента](ai-assistant/#работа-с-ai-ассистентом). На странице рабочего пространства чат встроен в страницу, поэтому кнопка недоступна; - «Мои активности» — открывает панель с запусками ваших действий и процессов. Пока у вас выполняются процессы, значок кнопки заменяется индикатором, а на вкладке «Процессы» отображается число выполняющихся процессов. ## Глобальный поиск diff --git a/content/documentation/user/mcp-management.ru.md b/content/documentation/user/mcp-management.ru.md index 101bf20b..5bb772eb 100644 --- a/content/documentation/user/mcp-management.ru.md +++ b/content/documentation/user/mcp-management.ru.md @@ -22,23 +22,53 @@ description: Подключение upstream MCP-серверов, пользо - `external` — инструменты, полученные из подключённого upstream MCP-сервера; - `custom` — пользовательские MCP-инструменты. -Вызов инструментов типов `external` и `custom` доступен только в том случае, если они входят во включённую MCP-коллекцию, к которой у пользователя есть доступ. +Любой инструмент, включая `internal`, доступен только через включённую MCP-коллекцию, которую пользователь может использовать. Права на действие с объектом портала проверяются при вызове отдельно. ## MCP-серверы Подключите upstream MCP-сервер, чтобы импортировать его инструменты в каталог портала. 1. Перейдите в «AI» → «MCP» → «MCP-серверы». -1. Нажмите «Подключить». +1. Нажмите «Подключить MCP-сервер». 1. На вкладке «Основная информация» укажите «Название», «Идентификатор», «Описание», «Владелец» и «Команда владелец». -1. На вкладке «Конфигурация»: +1. На вкладке «Авторизация»: 1. Включите переключатель «Включить». 1. Выберите «Транспорт» (`HTTP` или `SSE`). 1. Укажите «URL» upstream MCP-сервера. 1. При необходимости добавьте «Заголовки» и «Учётные данные» для авторизации. 1. Нажмите «Сохранить». -После сохранения откройте карточку сервера и нажмите «Синхронизировать», чтобы загрузить каталог инструментов. На вкладке «Инструменты» включите нужные инструменты и при необходимости задайте «Теги». +После сохранения откройте карточку сервера и нажмите «Синхронизировать», чтобы загрузить каталог инструментов. На вкладке «Инструменты» включите нужные инструменты и при необходимости задайте «Теги». Включите их в коллекцию, чтобы предоставить доступ пользователям и агентам. + +Чтобы подготовить подключение без доступа к его инструментам, сохраните сервер с выключенным переключателем «Включить». Он останется выключенным после создания; инструменты станут доступны для вызовов только после его включения и выдачи доступа через коллекции. + +### Учётные записи + +Для синхронизации каталога и проверки доступности выберите «Системная учётная запись» и заполните у неё реквизиты, используемые в заголовках. Она нужна для этих операций и тогда, когда сервер не требует авторизации. + +Вызовы инструментов по умолчанию используют реквизиты вызывающего пользователя. Чтобы всегда обращаться к серверу с реквизитами определённого пользователя, включите «Выбрать учётную запись для вызовов» и заполните «Учётная запись для вызовов». Системная учётная запись синхронизации сама по себе не меняет реквизиты вызовов. + +### Автоматическая синхронизация + +На вкладке «Авторизация» включите «Периодическая синхронизация», задайте «Периодичность запуска» в формате cron и выберите системную учётную запись. Без автоматической синхронизации обновляйте каталог кнопкой «Синхронизировать». + +Каталог заменяется только после успешного получения полного списка инструментов. Неудачная синхронизация сохраняет последний успешный каталог и показывает «Каталог устарел: последняя синхронизация не удалась». Изменение списка на внешнем сервере вступает в силу после успешной синхронизации. + +### Проверка доступности и ошибки + +Кнопка «Проверить доступность» проверяет соединение с сервером, но не обновляет каталог. Состояние соединения и актуальность каталога показываются отдельно: + +| Состояние | Что проверить | +| --- | --- | +| «Неизвестно» | Выполните проверку доступности или синхронизацию | +| «Работает» | Последнее обращение успешно; отдельно проверьте время синхронизации каталога | +| «Нестабильно», «Недоступен» | Сеть, URL, TLS, доступность внешнего сервера | +| «Ошибка» | Учётные данные выбранных учётных записей, настройки и ответы MCP-сервера | +| «Каталог ещё не синхронизирован» | Выполните первую успешную синхронизацию | + +Если системная учётная запись или учётная запись для вызовов заблокирована либо не выбрана, измените настройки сервера. После исправления реквизитов проверьте операцию именно с исправленной учётной записью: успешный вызов с личными реквизитами другого пользователя не снимает ошибку настроенной учётной записи. + +Ошибки авторизации личных реквизитов относятся к вызывающему пользователю и не означают недоступность сервера для всех. При сетевой ошибке проверьте результат изменяющей операции во внешней системе перед повтором. ## MCP-инструменты @@ -53,9 +83,11 @@ description: Подключение upstream MCP-серверов, пользо 1. При необходимости укажите «Сопоставление path-параметров» — объект `JSON`, который сопоставляет имена аргументов с сегментами `{placeholder}` в URL исполнителя. 1. При необходимости укажите «Сопоставление query-параметров» — объект `JSON`, который сопоставляет имена аргументов с именами query-параметров URL. 1. При необходимости укажите «Сопоставление body-параметров» — объект `JSON`, который сопоставляет имена аргументов с именами полей JSON-тела запроса. -1. На вкладке «Авторизация» укажите «URL» эндпоинта исполнителя, «HTTP-метод», «Заголовки» и «Учётные данные». В URL можно использовать сегменты `{placeholder}` для path-параметров и плейсхолдеры учётных данных, например `{{ .credentials.tenant_id }}`. +1. На вкладке «Авторизация» укажите «URL» эндпоинта исполнителя, «HTTP-метод», «Заголовки» и «Учётные данные». При необходимости включите «Выбрать учётную запись для вызовов», чтобы использовать реквизиты выбранного пользователя вместо вызывающего. В URL можно использовать сегменты `{placeholder}` для path-параметров и плейсхолдеры учётных данных, например `{{ .credentials.tenant_id }}`. 1. Нажмите «Сохранить». +Сохраните инструмент с выключенным переключателем «Включить», если его пока нельзя использовать. Выключенное состояние сохраняется при создании; для вызовов инструмент потребуется включить и добавить в доступную коллекцию. + Пример. В схеме аргументов задан аргумент `space_id`, URL исполнителя — `https://api.example.com/v1/spaces/{spaceId}/boards`, сопоставление path-параметров — `{"space_id": "spaceId"}`. При вызове инструмента с `space_id=42` запрос будет отправлен по адресу `https://api.example.com/v1/spaces/42/boards`. Аргументы передаются эндпоинту исполнителя следующим образом: @@ -66,19 +98,34 @@ description: Подключение upstream MCP-серверов, пользо ## MCP-коллекции -MCP-коллекция объединяет инструменты из каталога и определяет, какие из них доступны пользователям AI-ассистента и внешним MCP-клиентам. +MCP-коллекция объединяет инструменты и определяет, какие из них доступны пользователю и агенту. Она может содержать отдельные инструменты, MCP-серверы целиком и группы инструментов портала целиком. -1. Перейдите в «AI» → «MCP» → «MCP-коллекции». -1. Нажмите «Создать». -1. На вкладке «Основная информация» укажите «Название», «Идентификатор», «Описание», «Владелец» и «Команда владелец». -1. На вкладке «Конфигурация»: - 1. Включите переключатель «Включить». - 1. В поле «Инструменты» выберите инструменты из доступного каталога. Каждый пункт содержит идентификатор MCP-сервера в скобках. +### Создание коллекции + +Чтобы подготовить фиксированный набор инструментов чтения каталога: + +1. Откройте «AI» → «MCP» → «MCP-коллекции» и нажмите «Создать коллекцию». +1. Заполните название, идентификатор, описание, владельца и команду. +1. Включите коллекцию переключателем «Включить». +1. В составе коллекции нажмите «Добавить в коллекцию» и выберите отдельные инструменты `get_resources` и `get_resource_entities`. 1. Нажмите «Сохранить». +1. В меню коллекции выберите «Настроить доступ» и выдайте пользователям или командам роль с `use:mcp-collections`. + +Пользователь сможет вызывать эти инструменты из MCP-клиента с собственным API-токеном. Для агента дополнительно [подключите коллекцию к агенту](#связь-с-ai-ассистентом-и-mcp-сервером). Права на чтение ресурсов и сущностей каталога предоставляются отдельно. + +### Группы и серверы целиком + +В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», «Обозреватель каталога» или «Курируемые», либо «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. + +«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Состав инструментов и примеры вызовов — [в справочнике MCP](mcp-server/#инструменты-работы-с-каталогом). «Курируемые» объединяет специализированные инструменты с префиксом `curated_`, включая запуск процессов, чтение навыков и подготовку рабочих пространств. -Чтобы пользователь мог вызывать инструменты коллекции, откройте меню карточки коллекции и выберите «Настроить доступ». Назначьте пользователям или командам роль с разрешением `use:mcp-collections`. Список разрешений приведён в [ролевой модели](../../admin/security/rbac/#mcp-коллекции). +Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией. -Владелец коллекции и супер-администратор получают доступ к коллекции автоматически. +Если набор должен оставаться фиксированным, добавляйте отдельные инструменты. Группы могут включать операции изменения и удаления данных; проверяйте их состав перед выдачей доступа. + +### Доступ и включение + +Выключенная коллекция не предоставляет инструменты. Владение коллекцией и участие в её команде дают права при включённой настройке `owner-is-admin`; доступ остальных пользователей задаётся ролями. Супер-администратор имеет доступ ко всем коллекциям. ## Каталог @@ -86,8 +133,20 @@ MCP-коллекция объединяет инструменты из ката ## Связь с AI-ассистентом и MCP-сервером -Инструменты из MCP-коллекций используются следующим образом: +Чтобы выдать инструменты агенту: + +1. Откройте редактирование агента в «AI» → «Агенты» → «Каталог». +1. На вкладке «Инструменты и навыки» выберите «MCP-коллекции» и сохраните. +1. Убедитесь, что запускающему пользователю разрешены нужные инструменты через доступные ему коллекции. +1. Выдайте пользователю право использовать агента и необходимые права на объекты портала. +1. Запустите новый диалог или задание и проверьте вызов инструмента. + +Набор инструментов запуска — пересечение инструментов коллекций агента и инструментов, доступных запускающему пользователю. Пользователь может получать тот же инструмент через другую коллекцию; совпадение самой коллекции не требуется. + +Без коллекций агент работает без MCP-инструментов. Правило действует для платформенного и внешних агентов в ассистенте, виджете и процессе. Для агента из источника коллекции задаёт источник. + +[Внешний MCP-клиент](mcp-server/) использует коллекции своего пользователя; привязка к агенту для него не требуется. [Рабочее пространство](workspaces/) вызывает MCP от имени владельца и использует его доступ к инструментам. + +## Настройка после обновления -- В [AI-ассистенте](../ai-assistant/#инструменты-mcp) по кнопке «Инструменты» отображаются встроенные инструменты и инструменты из доступных коллекций. Платформенный агент в AI-ассистенте может вызывать инструменты из доступных пользователю коллекций; внешний агент — только инструменты из списка «MCP-инструменты» своего подключения. -- [AI-агенты](../admin/ai-agents/overview/#инструменты-агента) в шагах процессов вызывают только инструменты из списка «MCP-инструменты» своего подключения. -- [MCP-сервер](../mcp-server/) портала возвращает и вызывает те же инструменты из коллекций, которые доступны пользователю с учётом его прав RBAC. +При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 65af384e..e4446ed9 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -13,107 +13,138 @@ MCP-сервер — компонент Deckhouse Development Portal (DDP, по MCP — это открытый протокол для взаимодействия AI-моделей с внешними системами. Подробнее о протоколе можно узнать на [официальном сайте MCP](https://modelcontextprotocol.io/). {{< alert level="info" >}} -Помимо встроенных инструментов портала, MCP-сервер может вызывать инструменты из [MCP-коллекций](../mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. Настройка MCP-серверов, пользовательских MCP-инструментов и коллекций выполняется в разделе [«Управление MCP»](../mcp-management/). +Все инструменты портала и подключённых серверов доступны через [MCP-коллекции](../mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. Настройка MCP-серверов, пользовательских MCP-инструментов и коллекций выполняется в разделе [«Управление MCP»](../mcp-management/). {{< /alert >}} ## Доступные инструменты -Ниже перечислены **встроенные** инструменты портала. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. +Инструменты портала включают операции API и специализированные инструменты с префиксом `curated_`. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. -### get_resources +### Названия инструментов -Получить список ресурсов. +В MCP-клиенте используйте название из `tools/list`. Платформенный агент и OpenCode рабочего пространства показывают модели те же инструменты с дополнительным префиксом `ddp_`. При настройке коллекции выбирайте название без этого префикса: -Параметры: нет. +| Назначение | MCP-клиент и каталог коллекций | Название для модели агента | +| --- | --- | --- | +| Операция API | `get_resources` | `ddp_get_resources` | +| Обозреватель каталога | `query_catalog` | `ddp_query_catalog` | +| Специализированный запуск процесса | `curated_run_process` | `ddp_curated_run_process` | +| Чтение навыка | `curated_get_skill` | `ddp_curated_get_skill` | -Возвращает: список ресурсов. +Ниже приведены названия для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте `ddp_`; внешний агент может задавать собственное представление названий для модели. -Пример: - -```text -Получи список ресурсов -``` - ---- - -### get_external_services +### Инструменты операций API -Получить список внешних сервисов (GitLab, SonarQube и т. д.). +В «AI» → «MCP» → «Каталог» отображаются названия инструментов, например `get_resources` и `get_resource_entities`, их описания и соответствующие HTTP-методы и пути API. По нажатию на название инструмента открывается схема его аргументов. Инструменты объединены в группы, например «Каталог», «Обозреватель каталога», «Действия», «Процессы и автоматизации» и «Рабочие пространства». Специализированные инструменты находятся в группе «Курируемые». -Параметры: нет. +Аргументы инструмента описаны в `inputSchema` ответа `tools/list`. Например, `run_process` — операция API, а `curated_run_process` — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются. -Возвращает: список внешних сервисов. +Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например: -Пример: - -```text -Получи список внешних сервисов +```json +{ + "status": 200, + "contentType": "application/json; charset=utf-8", + "encoding": "json", + "body": [] +} ``` ---- +Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Неуспешный вызов возвращает MCP-результат с `isError: true`; ошибки «Обозревателя каталога» также поясняют, как исправить запрос. -### get_resource_entities +### Инструменты работы с каталогом -Получить все сущности выбранного ресурса. +Инструменты группы «Обозреватель каталога» ищут и подсчитывают сущности, получают схему свойств и граф связей, разбирают запуски процессов и проверяют готовность запуска. Все эти инструменты только читают данные; проверка готовности не запускает процесс. -Параметры: +Результаты и счётчики ограничены доступными пользователю данными. Если видна хотя бы одна сущность, инструменты также показывают схему её ресурса для запросов по свойствам. Обход связей не проходит через недоступные сущности. -| Название | Тип | Обязательность | Описание | -|------------------|--------|----------------|---------------| -| `resource_uuid` | строка | Да | UUID ресурса | +В каталоге коллекций и внешнем MCP-клиенте используются следующие названия. Для модели платформенного агента и OpenCode к ним добавляется `ddp_`, например `ddp_query_catalog`: -Возвращает: список сущностей ресурса. +| Инструмент | Назначение | +| --- | --- | +| `describe_me` | Текущий пользователь, команды, роли, разрешения, время и часовой пояс | +| `get_catalog_schema` | Видимые ресурсы, свойства и типы связей; с `resource` — подробности одного ресурса | +| `search_catalog` | Поиск ресурсов, команд и сущностей по словам | +| `query_catalog` | Фильтрация, подсчёт и группировка сущностей | +| `get_entity_summary` | Карточка сущности со свойствами, проверками, связями и последними запусками | +| `get_entity_relation_graph` | Обход связей с глубиной и путём от исходной сущности | +| `list_process_runs` | Поиск, подсчёт и группировка запусков процессов | +| `get_process_run` | Диагностика запуска по событиям текущей попытки: ошибки, подтверждения, повторы и таймеры | +| `find_operations` | Процессы и действия, доступные для чтения и привязанные к ресурсу сущности | +| `check_process_readiness` | Проверка параметров и условий запуска процесса без выполнения | -Пример: +Описание и точные аргументы доступны в «AI» → «MCP» → «Каталог» и в `inputSchema` ответа `tools/list`. -```text -Получи все сервисы и покажи название и дату создания -``` +Следующие примеры показывают объект `params` для `tools/call`. При передаче тела запроса API используйте аргумент `body`. Сначала вызовите `get_catalog_schema`, чтобы узнать существующие идентификаторы ресурсов, свойств и связей. Идентификаторы `services` и `language` в примере замените на значения своей установки. ---- +#### Сущности моих команд -### get_entity +Запрос группирует сервисы команд текущего пользователя по языку разработки: -Получить одну сущность по UUID. +```json +{ + "name": "query_catalog", + "arguments": { + "body": { + "resource": "services", + "where": {"field": "team", "op": "in", "value": {"context": "myTeams"}}, + "groupBy": "properties.language" + } + } +} +``` -Параметры: +`{"context":"myTeams"}` подставляет команды вызывающего пользователя. Для фильтра по владельцу используется `{"context":"me"}`. `countOnly: true` возвращает количество сущностей без списка; `groupBy` возвращает группы с их счётчиками. В сгруппированном ответе `total` — число групп, `entities` — число найденных сущностей. -| Название | Тип | Обязательность | Описание | -|-----------------|--------|----------------|---------------| -| `entity_uuid` | строка | Да | UUID сущности | +Для выборки нескольких условий объедините их в `where.and` или `where.or`. Доступны сравнения `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `containsAny`, `isEmpty`, `isNotEmpty` и `between`; набор зависит от типа поля. Обращение к `properties.<идентификатор>` требует параметра `resource`. -Возвращает: данные одной сущности. +#### Неуспешные запуски за вчера -Пример: +Запрос выбирает запуски со статусом `Failed` за предыдущий календарный день в часовом поясе Москвы: -```text -Получи сущность с UUID 3fa85f64-5717-4562-b3fc-2c963f66afa6 +```json +{ + "name": "list_process_runs", + "arguments": { + "body": { + "status": ["Failed"], + "team": {"context": "myTeams"}, + "since": {"calendar": "day", "offset": -1}, + "timezone": "Europe/Moscow", + "limit": 20 + } + } +} ``` ---- +Для скользящего периода используйте `since: {"last":"24h"}`. `countOnly: true` возвращает количество запусков; `groupBy` группирует их по `status`, `process`, `initiator`, `entity` или `day`. Эти два режима не совмещаются. Для диагностики передайте UUID найденного запуска в `get_process_run` как `run_uuid`. -### get_entity_relations +В чате портал передаёт часовой пояс браузера. Внешний MCP-клиент задаёт `timezone` явно; без него используется UTC. Неизвестный часовой пояс отклоняет запрос. -Получить связи сущности. +#### Проверка перед запуском процесса -Параметры: +Перед выполнением используйте последовательность: -| Название | Тип | Обязательность | Описание | -|------------------|--------|----------------|------------------------| -| `resource_uuid` | строка | Да | UUID ресурса | -| `entity_slug` | строка | Да | Идентификатор сущности | +1. Найдите сущность через `search_catalog` и получите доступные операции через `find_operations`. +1. Передайте UUID ресурса, сущности и процесса в `check_process_readiness`. В `body` укажите значения запуска: `selectedProperties`, `actions`, `context`, `skippedElementUuids` и `agentProviderRefs`, когда они нужны. +1. Проверьте `ready`, `blockers` и `approvalRequired`. Проверка возвращает первое препятствие; исправьте его по подсказке и повторите вызов. Значения по умолчанию здесь не подставляются. +1. Для выполнения отдельно вызовите операцию API `run_process` либо специализированный `curated_run_process` с его собственной схемой аргументов. -Возвращает: список связей сущности. +Проверка требует `control:processes` глобально, на ресурс или сущность. Читаемая операция не обязательно доступна для запуска. Между проверкой и запуском состояние может измениться, поэтому итоговый результат проверяется по ответу запуска. -Пример: +#### Ограничения и неполные ответы -```text -Получи связи сущности «api-gateway» ресурса «Сервисы» -``` +При работе со списками учитывайте размер ответа и ограничения запроса: ---- +- `limit` по умолчанию равен `20`, максимум — `500`. Если `hasMore: true`, продолжайте с `offset`, увеличенным на `returned`. При ограничении размера ответа строк может быть меньше, чем запрошено. +- Для графа связей `depth` задаётся от `1` до `5`. При `truncated: true` следуйте `hints`: уточните тип связи, глубину или лимит. Граф не поддерживает `offset`. +- Дерево `where` допускает до четырёх уровней вложенности и 20 условий. Если запрос слишком сложен, сузьте выборку или глубину обхода связей. +- Карточка `get_entity_summary` сокращает длинные описания и значения. Для полного поля используйте `query_catalog` с `fields` и фильтром по UUID. +- Диагностика запуска отмечает недостающие факты в `unknown`. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки. + +При отказе инструмент возвращает `isError: true` с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос. -### get_external_data +### curated_get_external_data Выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя. @@ -139,41 +170,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_actions - -Получить список действий с описанием входных параметров. - -Параметры: нет. - -Возвращает: для каждого действия — UUID, идентификатор, название, описание, тип, признак подтверждения `approval`, привязанные ресурсы и параметры пользовательской формы. Для параметров типов Enum и List возвращаются варианты значений. Тело действия и настройки запроса не возвращаются. - -Действие с `approval: true` при запуске ожидает подтверждения. - -Пример: - -```text -Получи список действий -``` - ---- - -### get_datasources - -Получить список источников данных. - -Параметры: нет. - -Возвращает: список источников данных. - -Пример: - -```text -Получи список источников данных -``` - ---- - -### get_processes +### curated_get_processes Получить список процессов с параметрами запуска. @@ -183,7 +180,7 @@ MCP — это открытый протокол для взаимодейств |---|---|---|---| | `include_step_properties` | булево | Нет | Вернуть также задачи процесса, которые принимают собственные значения параметров действия. По умолчанию выключено | -Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Схема элементов процесса не возвращается. +Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Поле `contextPathsComplete` показывает, учтены ли тела действий при сборе путей; перед подготовкой запуска запросите `include_step_properties: true`. Схема элементов процесса не возвращается. Пример: @@ -193,7 +190,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_service_templates +### curated_get_service_templates Получить шаблоны микросервисов из реестра шаблонов. @@ -213,7 +210,7 @@ MCP — это открытый протокол для взаимодейств --- -### run_process +### curated_run_process Запустить процесс для сущности. @@ -225,7 +222,7 @@ MCP — это открытый протокол для взаимодейств | `entity_uuid` | строка | Да | UUID сущности ресурса, к которому привязан процесс | | `properties` | объект | Да | Параметры запуска процесса: идентификатор параметра → значение. Не переданные параметры получают значения по умолчанию. Если задавать нечего, передайте `{}` | | `context` | объект | Нет | [Контекст запуска](../admin/processes/overview/#контекст-запуска), доступный в шаблонах процесса как `.context` | -| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `get_processes` с `include_step_properties` | +| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `curated_get_processes` с `include_step_properties` | | `skipped_element_uuids` | массив | Нет | UUID элементов «AI-агент» и «Шаблон», которые пропускаются в этом запуске | | `agent_provider_refs` | объект | Нет | AI-провайдеры для элементов «AI-агент»: UUID элемента → название провайдера | @@ -242,49 +239,52 @@ MCP — это открытый протокол для взаимодейств --- -### get_process_instances +### curated_get_process_instance -Получить запуски процессов сущности, новые первыми. +Получить один запуск процесса с хранилищем. Параметры: | Название | Тип | Обязательность | Описание | |---|---|---|---| | `entity_uuid` | строка | Да | UUID сущности | -| `process_uuid` | строка | Нет | Вернуть только запуски этого процесса | -| `status` | строка | Нет | Вернуть только запуски с этим статусом, например `Running` или `Completed` | -| `page` | число | Нет | Номер страницы, начиная с 1 | -| `per_page` | число | Нет | Число запусков на странице. По умолчанию — 10 | +| `instance_uuid` | строка | Да | UUID запуска процесса из `get_entity_process_history` или из ответа `curated_run_process` | +| `wait_seconds` | число | Нет | Сколько секунд ждать завершения запуска, не больше 45. Без параметра ответ возвращается сразу | -Возвращает: список запусков процессов со статусом и временем создания. +Возвращает: статус запуска, время, активные элементы и [хранилище процесса](../admin/processes/store/). Для статусов `Failed`, `Timeout` и `Partially Completed` ответ содержит поле `failureReason`: элемент, на котором произошла ошибка, итоговое сообщение и последние строки лога этого элемента. Пример: ```sh -Идёт ли ещё какой-нибудь процесс по сущности «api-gateway» +Покажи результат экземпляра процесса 3fa85f64-5717-4562-b3fc-2c963f66afa6 ``` ---- +### Навыки -### get_process_instance +Инструменты чтения [навыков](../admin/ai-agents/skills/) передают инструкции и дополнительные файлы: -Получить один запуск процесса с хранилищем. +| Инструмент | Аргументы | Результат | +| --- | --- | --- | +| `curated_list_skills` | Необязательная строка `q` | Доступные пользователю навыки с описаниями и последними версиями | +| `curated_get_skill` | Обязательный `name`, необязательный `version` | Текст `SKILL.md`, версия и список файлов | +| `curated_get_skill_file` | Обязательные `name` и `path`, необязательный `version` | Текст дополнительного файла | -Параметры: +В обычном MCP-клиенте версия выбирается меткой; без неё используется последняя активная. В запуске агента доступ ограничен назначенными ему навыками и зафиксированными версиями. Бинарные файлы и файлы больше 1 МиБ через `curated_get_skill_file` не читаются. -| Название | Тип | Обязательность | Описание | -|---|---|---|---| -| `entity_uuid` | строка | Да | UUID сущности | -| `instance_uuid` | строка | Да | UUID запуска процесса из `get_process_instances` или из ответа `run_process` | -| `wait_seconds` | число | Нет | Сколько секунд ждать завершения запуска, не больше 45. Без параметра ответ возвращается сразу | +### Рабочие пространства -Возвращает: статус запуска, время, активные элементы и [хранилище процесса](../admin/processes/store/). Для статусов `Failed`, `Timeout` и `Partially Completed` ответ содержит поле `failureReason`: элемент, на котором произошла ошибка, итоговое сообщение и последние строки лога этого элемента. +Инструменты позволяют подготовить [рабочее пространство](workspaces/) из чата: -Пример: +| Инструмент | Аргументы | Результат | +| --- | --- | --- | +| `curated_get_workspace_templates` | Нет | Доступные шаблоны с активной версией, настройками репозитория и параметрами | +| `curated_create_workspace` | Обязательные `template_uuid`, `name`, `ttl_hours`; необязательные `provider`, `repository_url`, `base_ref`, `entity_uuid`, `parameters` | Состояние созданного пространства; операция выполняется асинхронно | +| `curated_get_workspace` | Обязательный `workspace_uuid`, необязательный `wait_seconds` до 45 | Статус, готовность, последняя ошибка и активная операция | +| `curated_attach_workspace` | Обязательный `workspace_uuid` | Прикрепление пространства к текущему чату | -```sh -Покажи результат экземпляра процесса 3fa85f64-5717-4562-b3fc-2c963f66afa6 -``` +`provider` можно не передавать, когда подходящий провайдер уже задан в контексте чата. При вызове вне такого контекста укажите его явно. `parameters` — объект значений переменных шаблона; `ttl_hours` — целое число от 1 до 720. + +`curated_attach_workspace` работает только в контексте агента, отвечающего в чате портала. Используйте последовательность: получить шаблоны, создать пространство, дождаться готовности, прикрепить его к чату. ## Подключение MCP-сервера @@ -371,7 +371,7 @@ Content-Type: application/json "content": [ { "type": "text", - "text": "[{\"uuid\":\"...\",\"name\":\"Service 1\",\"properties\":{...}},...]" + "text": "{\"status\":200,\"contentType\":\"application/json; charset=utf-8\",\"encoding\":\"json\",\"body\":{\"response\":[],\"error\":null}}" } ] } @@ -388,7 +388,7 @@ Content-Type: application/json Права доступа: - Инструменты работают с теми же правами, что и пользователь. -- Инструменты `run_process` и `get_external_data` изменяют данные: первый запускает процесс, второй может выполнить запрос `POST`, `PUT`, `PATCH` или `DELETE` к внешнему сервису. +- `curated_run_process`, `curated_create_workspace`, `curated_attach_workspace` и изменяющие операции API выполняют действия от имени пользователя. `curated_get_external_data` также может отправить `POST`, `PUT`, `PATCH` или `DELETE` во внешний сервис. - Если у вас нет доступа к ресурсу, инструмент вернёт ошибку доступа. - Данные фильтруются в соответствии с вашими правами RBAC. diff --git a/content/documentation/user/overview.ru.md b/content/documentation/user/overview.ru.md index d5971f97..1e0bee2d 100644 --- a/content/documentation/user/overview.ru.md +++ b/content/documentation/user/overview.ru.md @@ -1,6 +1,19 @@ --- title: Обзор weight: 10 +description: "Основные сценарии пользователя DDP: каталог, процессы, AI-ассистент и рабочие пространства." --- -Данный документ представляет собой руководство пользователя Deckhouse Development Portal (DDP) и является частью эксплуатационной документации продукта. +Deckhouse Development Portal (DDP) объединяет каталог сервисов, действия, процессы и инструменты AI. Начните со сценария, который нужен для работы: + +| Задача | Руководство | +| --- | --- | +| Найти сервис и его связи | [Каталог](catalog/) | +| Запустить действие или процесс | [Страница сущности](catalog/#страница-сущности) | +| Подключить языковую модель | [AI-провайдер в профиле](ai-assistant/#подключение-ai-провайдера) | +| Создать IDE с агентом для проекта | [Создание рабочего пространства](workspaces/#создание-рабочего-пространства) | +| Поручить агенту изменить файлы | [Чат рабочего пространства](workspace-chat/) | +| Подключить MCP-клиент | [MCP-сервер](mcp-server/#подключение-mcp-сервера) | +| Посмотреть использование AI | [Статистика AI](ai-statistics/) | + +Набор доступных действий определяется ролями и доступом к конкретным объектам. Для рабочих пространств администратор предварительно подготавливает шаблоны и лимиты. diff --git a/content/documentation/user/properties.ru.md b/content/documentation/user/properties.ru.md index a4e93a27..46e9cfd7 100644 --- a/content/documentation/user/properties.ru.md +++ b/content/documentation/user/properties.ru.md @@ -1,5 +1,6 @@ --- title: Параметры +description: Типы параметров каталога и форм, настройка обязательности, редактирования и видимости. --- Для каждого ресурса, действия или сценария администратор DDP может добавить неограниченное количество параметров одного из следующих типов: @@ -50,6 +51,8 @@ title: Параметры ## Конфигурация +Новый параметр в редакторе по умолчанию необязателен, доступен для редактирования и виден пользователю. Включите «Обязательный параметр», если его значение требуется для сохранения формы или запуска. Настройки задаются отдельно для каждого параметра: + * «Редактируемый параметр» — для каждого параметра можно настроить разрешение либо запрет редактирования пользователем. В случае запрета редактирования пользователь при запуске действий или сценариев не сможет изменить значение параметра, то есть всегда будет использоваться значение по умолчанию. * «Обязательный параметр» — каждый параметр может быть обязательным либо опциональным. Значение обязательного параметра не может быть пустым при запуске действий, сценариев и процессов и при сохранении [формы сущности](../catalog/#создание-и-редактирование-сущности). Параметр типа «Boolean» всегда имеет значение. Значение опционального параметра может оставаться пустым без влияния на работоспособность действия. При создании и изменении сущности через API, источники данных и действия обязательность параметров ресурса не проверяется. * «Скрытый параметр» — скрытый параметр не отображается в таблицах и карточках сущностей, а также при запуске действий и сценариев. diff --git a/content/documentation/user/workspace-chat.ru.md b/content/documentation/user/workspace-chat.ru.md new file mode 100644 index 00000000..ff859786 --- /dev/null +++ b/content/documentation/user/workspace-chat.ru.md @@ -0,0 +1,66 @@ +--- +title: Чат рабочего пространства +description: Задания AI-агенту рабочего пространства, подтверждения действий, очередь сообщений, изменения файлов и контекст. +weight: 56 +--- + +Чат на странице [рабочего пространства](workspaces/) обращается к его агенту OpenCode. К тому же пространству можно прикрепить чат AI-ассистента; он также переключится на OpenCode. Агент получает доступ к рабочим файлам и терминалу. Выбранный для обычного чата агент из каталога в этом режиме не выполняет задачу. + +## Начало работы + +Чтобы продолжить работу с проектом в чате: + +1. Создайте и запустите рабочее пространство. +1. В разделе «Главная» → «AI-инструменты» → «Рабочие пространства» нажмите «Открыть» в карточке. Чат расположен на странице пространства. Для существующего чата используйте кнопку «Прикрепить рабочее пространство» в AI-ассистенте. +1. Проверьте прикреплённое пространство и отправьте задачу. +1. Во время выполнения отвечайте на вопросы и запросы подтверждения агента. +1. Проверьте итоговый ответ и изменения файлов. + +На странице пространства кнопка AI-ассистента в верхней панели недоступна: используйте встроенный чат. + +Чат и IDE используют одну рабочую копию. Открывайте IDE для просмотра и редактирования файлов, запуска тестов и работы с Git. + +## Подтверждения действий + +В чате предусмотрены режимы «Автоматически» и «Подтверждать». Во втором режиме агент запрашивает разрешение на действия, которые требуют подтверждения, например выполнение команды. + +Для каждого запроса проверьте действие и выберите «Разрешить», «Отклонить» или «Разрешать всегда в этом рабочем пространстве». Разовое разрешение действует на текущий запрос. Постоянное разрешение сохраняет правило для последующих совпадающих запросов во всех чатах пространства; его можно удалить через «Разрешено всегда». При отказе комментарий задаёт агенту, что сделать вместо действия; отказ без комментария останавливает задание. + +Навык может содержать инструкции и скрипты, но сам по себе не предоставляет новых прав на объекты портала. Инструменты MCP выполняются с правами владельца рабочего пространства. + +## Очередь и остановка + +Пока агент отвечает, следующие сообщения попадают в очередь. В очереди рабочего пространства может ожидать до 10 заданий. Можно забрать ожидающее сообщение из очереди до начала его выполнения. + +Если пространство не приняло сообщение, например из-за заполненной очереди или недоступности агента, вопрос остаётся в истории чата с причиной ошибки. Он сохраняет своё место среди других сообщений после перезагрузки. Устраните причину и повторите отправку; такое сообщение ещё не является заданием рабочего пространства. + +Кнопка остановки прерывает текущее задание агента. Чтобы остановить также IDE и под рабочего пространства, используйте «Остановить» в карточке пространства. + +Отсоединение рабочего пространства от чата возвращает чат к агенту из каталога и оставляет само пространство работающим. + +## Ошибки отправки + +Если задание не принято, проверьте указанную в чате причину: + +| Сообщение | Действие | +| --- | --- | +| «Очередь вопросов рабочего пространства заполнена. Дождитесь ответов и повторите попытку.» | Дождитесь выполнения заданий или уберите ненужные вопросы из очереди, затем повторите отправку | +| «Агент рабочего пространства недоступен. Проверьте статус и диагностику рабочего пространства.» | Проверьте, что пространство запущено и готово, затем откройте его диагностику | +| «Рабочее пространство, прикреплённое к чату, не найдено. Прикрепите другое.» | Прикрепите доступное пространство | +| «Рабочее пространство отвечает на другой вопрос. Дождитесь завершения и повторите попытку.» | Дождитесь завершения текущего задания и повторите отправку | + +## Изменения файлов + +После задания просмотрите список изменённых файлов и разницу содержимого. Уточняйте в следующем сообщении конкретные файлы и ожидаемый результат: + +```text +Оставь обработчик /healthz без обращения к базе данных. Обнови тест и повторно запусти его. Покажи результат теста и итоговые изменения. +``` + +Файлы сохраняются на томе рабочего пространства. Для передачи результата другим участникам проекта создайте коммит и отправьте его в Git либо попросите агента выполнить эти действия явно. + +## Контекст и статистика + +Сессия агента хранит историю работы в пространстве. При длинном диалоге нажмите «Сжать контекст»; операция отображается отдельным заданием со статусом «Сжатие контекста». + +Расход токенов, длительность заданий и ожидание подтверждений доступны [в статистике AI](ai-statistics/). Ответы агента, выполненные команды и запросы подтверждения сохраняются в истории чата. diff --git a/content/documentation/user/workspaces.ru.md b/content/documentation/user/workspaces.ru.md new file mode 100644 index 00000000..9469e01b --- /dev/null +++ b/content/documentation/user/workspaces.ru.md @@ -0,0 +1,152 @@ +--- +title: Рабочие пространства +description: Создание рабочего пространства с IDE и AI-агентом, работа с репозиторием, остановка, обновление и диагностика. +weight: 55 +--- + +Рабочее пространство — персональная IDE и AI-агент OpenCode в Kubernetes. Агент читает и изменяет файлы, выполняет команды и отвечает в чате рабочего пространства или AI-ассистента. IDE и чат работают с одними файлами; после остановки данные сохраняются на постоянном томе. + +Рабочее пространство создаётся из шаблона, который задаёт репозиторий, инструменты и параметры запуска. Рабочее пространство можно создать с репозиторием или с пустой рабочей директорией, если это предусмотрено шаблоном. + +## Ваши рабочие пространства + +Откройте «Главная» → «AI-инструменты» → «Рабочие пространства». Раздел показывает ваши рабочие пространства. + +Найдите пространство по названию или репозиторию и выберите фильтр состояния: «Все», «Работают», «Остановлены», «В процессе» или «Требуют внимания». Карточка показывает состояние, репозиторий и текущую операцию. Кнопка «Открыть» переходит на страницу с чатом агента; кнопка «IDE» открывает редактор. Над списком отображается использование настроенных лимитов. + +## Создание рабочего пространства + +Перед созданием подключите [AI-провайдера](ai-assistant/#подключение-ai-провайдера). Если шаблон использует личные реквизиты, заполните в профиле [учётные данные](credentials/) для его подключений Kubernetes и Git. + +Чтобы создать рабочее пространство с главной: + +1. Откройте «Главная» → «AI-инструменты» → «Рабочие пространства» и нажмите «Создать». +1. На шаге «Шаблон» выберите карточку шаблона и нажмите «Далее». Поиск отбирает шаблоны по названию и описанию. +1. На шаге «Параметры и запуск» укажите «Название» и проверьте версию шаблона. Для обычного запуска используйте активную опубликованную версию. +1. Если шаблон разрешает выбор репозитория, заполните «URL репозитория» и при необходимости «Ветка или тег». Пустая ветка означает основную ветку репозитория. URL должен использовать HTTPS и относиться к подключению Git шаблона. +1. При необходимости выберите «Ресурс сущности» и «Сущность каталога». Привязка задаётся при создании; она нужна, чтобы процессы сущности могли выполнять задания в этом рабочем пространстве. +1. Заполните обязательные параметры шаблона, выберите «AI-провайдер» и «Срок работы». Проверьте итоговые параметры справа и нажмите «Создать». +1. Дождитесь статуса «Работает». После создания открывается страница пространства; во время операции она показывает лог, а после запуска — чат агента. + +Если шаблонов нет или кнопка создания недоступна, обратитесь к администратору портала. + +## Страница рабочего пространства + +Страница открывается кнопкой «Открыть» в карточке. В центре расположен чат агента. Кнопки в заголовке открывают IDE и приложения, запускают и останавливают пространство. Обновление версии и удаление доступны в меню «Ещё». + +Кнопка «Подробнее» открывает боковую панель с вкладками «Операции», «Диагностика» и «Приложения и порты». Здесь можно проверить применение шаблона, состояние пода и публикации приложений. Чат остаётся на странице при открытии панели. + +Если пространство остановлено, запустите его для продолжения чата. При ошибке операции используйте «Показать лог» и «Повторить операцию» после устранения причины. Чат с агентом доступен только владельцу пространства. + +## Работа в IDE + +Откройте карточку работающего рабочего пространства и нажмите «Открыть IDE». Разрешите браузеру открыть новую вкладку. + +IDE открывается на отдельном HTTPS-домене. Вход проверяет портал; для повторного входа после истечения сессии используйте кнопку «Открыть IDE». Рабочая директория штатного шаблона — `/workspace/code`. + +В терминале IDE команда `opencode` подключается к тому же агенту, который отвечает в чате портала. Изменения файлов видны в IDE и в чате. Для сохранения результата в Git проверьте изменения, создайте коммит и отправьте его в репозиторий. + +## Приложения рабочего пространства + +На странице пространства нажмите «Подробнее» → «Приложения и порты». Здесь доступны приложения шаблона и опубликованные порты. В стартовом шаблоне приложение «Терминал» открывает командную строку в браузере с доступом к файлам рабочего пространства. Терминал предназначен для владельца рабочего пространства. + +Чтобы открыть приложение, нажмите «Открыть» в его карточке. Индикатор «Работает» означает, что порт слушается в поде; готовность самого приложения проверьте после открытия. После запуска сервера нажмите «Обновить», чтобы перечитать состояние портов. + +### Публикация порта + +Для предпросмотра веб-приложения опубликуйте его порт: + +1. Запустите HTTP-сервер в IDE, веб-терминале или через агента. Он должен быть доступен по `127.0.0.1` внутри пода. Публикация поддерживает HTTP и WebSocket. +1. Откройте «Подробнее» → «Приложения и порты» и нажмите «Опубликовать порт». Можно также нажать «Опубликовать» у нужного порта в блоке «Порты, которые слушаются в поде». +1. Заполните «Название», «Порт» и «Уровень доступа». Допустимые уровни ограничены шаблоном. +1. Подтвердите публикацию и откройте полученный адрес. При необходимости скопируйте его кнопкой «Скопировать адрес». + +Публиковать порты может владелец рабочего пространства. Публикация создаёт маршрут; сервер приложения запустите самостоятельно. Для сервера с проверкой заголовка `Host` разрешите внешний хост опубликованного порта. + +Адрес имеет вид `https://p1-ddp-ws-<суффикс>.<домен-рабочих-пространств>`. Количество свободных адресов задаёт шаблон; в стартовом шаблоне их восемь. Если свободных адресов нет, отмените ненужную публикацию. Порт, уже занятый приложением шаблона, повторно не публикуется. + +### Доступ по ссылке + +Перед передачей ссылки выберите подходящий «Уровень доступа»: + +| Уровень | Кто может открыть | +| --- | --- | +| «Только владелец» | Владелец рабочего пространства | +| «Пользователи DDP» | Любой вошедший в портал пользователь, который не заблокирован | +| «Публично» | Любой посетитель без входа в портал | + +Доступ по ссылке к приложению не предоставляет доступ к карточке пространства, IDE или чату. Веб-терминалы оставляйте доступными только владельцу: команды получают доступ к его файлам и токенам внутри пода. + +Уровень опубликованного порта меняется в его строке. Чтобы закрыть адрес и освободить место, нажмите «Отменить публикацию» и подтвердите действие. Сервер внутри пода при этом продолжает работать. Изменения маршрутов применяются в течение примерно 15 секунд. + +Остановка рабочего пространства делает приложения недоступными; после запуска опубликованные адреса снова используются. Если после обновления шаблона появился текст «Адрес не зарезервирован текущей версией шаблона», отмените такую публикацию и опубликуйте порт в свободный адрес. + +## Задание агенту в чате + +Чтобы агент изменил проект: + +1. Нажмите «Открыть» в карточке пространства на главной. Для существующего чата AI-ассистента используйте «Прикрепить рабочее пространство». +1. Убедитесь, что чат показывает прикреплённое рабочее пространство. +1. Отправьте задачу с ожидаемым результатом, например: + + ```text + Изучи проект, добавь проверку /healthz и тест для неё. Запусти связанные тесты и покажи изменённые файлы. Коммит не создавай. + ``` + +1. Проверьте ответ, выполненные команды и изменения файлов. + +Одновременно в рабочем пространстве выполняется одно задание. Следующие сообщения ожидают в очереди. Остановка ответа прерывает текущее задание; само рабочее пространство продолжает работать. + +Режим подтверждений задаёт, выполняет ли агент действия автоматически или запрашивает разрешение. В режиме с подтверждениями ответьте на запрос в чате; сохранённое разрешение на повторяющееся действие можно отозвать. Подробности — [в руководстве по чату рабочего пространства](workspace-chat/). + +## Остановка и срок работы + +Для остановки нажмите «Остановить» и подтвердите действие. IDE и текущее задание прерываются, файлы и состояние на постоянном томе сохраняются. + +«Срок работы» задаётся от 1 до 720 часов. По истечении срока портал останавливает рабочее пространство автоматически. Остановленные пространства не занимают места в лимите запущенных пространств; их постоянные тома продолжают занимать хранилище. + +Для продолжения нажмите «Запустить». При запуске штатный шаблон сохраняет существующую рабочую копию Git; повторное клонирование не выполняется. Изменения в удалённом репозитории получите обычными командами Git. + +## Обновление шаблона + +Публикация новой активной версии шаблона не обновляет существующие рабочие пространства автоматически. + +Чтобы применить новую версию: + +1. Остановите рабочее пространство. +1. Откройте меню «Ещё» → «Обновить версию». +1. Проверьте выбранную версию и параметры. Если активная опубликованная версия шаблона новее текущей, форма сразу предлагает её. Текущий черновик остаётся выбранным, если он доступен пользователю. При необходимости выберите другую доступную версию. Форма отмечает новые, удалённые и изменённые значения. +1. Подтвердите обновление и проверьте его результат на вкладке «Операции». Переход на другую версию доступен и без изменения значений параметров. +1. После успешного обновления запустите рабочее пространство. + +Данные постоянных томов сохраняются. Изменение шаблона, которое удаляет или заменяет существующий постоянный том, отклоняется. Файлы, которыми управляет шаблон, могут перезаписываться при следующем запуске. Перед обновлением сохраните нужные изменения в Git. + +## Диагностика + +На странице пространства нажмите «Подробнее» и найдите последнюю операцию с ошибкой. Используйте подходящую вкладку: + +| Вкладка | Что проверить | +| --- | --- | +| «Операции» | Вывод OpenTofu при создании, запуске, обновлении или удалении | +| «Диагностика» | Состояние StatefulSet, пода, контейнеров и постоянных томов, события Kubernetes, текущие и предыдущие логи контейнеров | + +Ошибки выполнения задания смотрите в чате агента. + +Типовые причины и действия: + +| Симптом | Действие | +| --- | --- | +| Не удаётся клонировать репозиторий | Проверьте URL и токен Git той учётной записи, которую использует шаблон | +| Под не скачивает образ | Передайте администратору сообщение об ошибке из диагностики | +| Постоянный том не готов | Передайте администратору сообщение об ошибке подключения хранилища | +| Ошибка контейнера `bootstrap` | Прочитайте его лог. Проверьте указанный репозиторий и учётные данные; ошибки шаблона передайте администратору | +| IDE не открывается при работающем поде | Повторно нажмите «Открыть IDE». Если ошибка сохраняется, передайте администратору адрес и сообщение браузера | +| Достигнут лимит запущенных пространств | Остановите ненужное пространство или попросите администратора изменить лимит | + +После устранения причины нажмите «Повторить операцию». + +## Удаление + +Перед удалением отправьте нужные изменения в Git или скопируйте файлы из IDE. На странице пространства откройте «Ещё» → «Удалить» и подтвердите действие. + +Удаление уничтожает объекты рабочего пространства в Kubernetes и постоянные данные. Остановка подходит для перерыва в работе, удаление — для окончательного освобождения ресурсов.