diff --git a/content/documentation/admin/ai-agents/agent-sources.ru.md b/content/documentation/admin/ai-agents/agent-sources.ru.md index 0e60e802..d795bb19 100644 --- a/content/documentation/admin/ai-agents/agent-sources.ru.md +++ b/content/documentation/admin/ai-agents/agent-sources.ru.md @@ -43,7 +43,7 @@ AI-агенты — функциональность на стадии Preview. 1. Создайте ресурс, сущности которого будут описывать агентов. Добавьте в ресурс параметр типа `String` для URL карточки агента, например `agent_card_url`. 1. Создайте сущности ресурса и заполните в них URL карточки. Идентификатор сущности станет идентификатором агента. 1. Перейдите в раздел «AI» → «AI-агенты» → «Источники агентов» и нажмите «Создать источник агентов». Кнопка доступна с разрешением `edit:ai-agents`. -1. На вкладке «Основная информация» включите «Включить источник», заполните «Название» и «Идентификатор». +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..8ba6717f 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» → «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-провайдера пользователя | @@ -96,7 +97,7 @@ API-ключ хранится в базе данных в зашифрованн Пример вызова инструмента: ```shell -curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-Token: " -H "Content-Type: application/json" -d '{"tool": "get_resources", "arguments": {}}' +curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-Token: " -H "Content-Type: application/json" -d '{"tool": "ddp_get_resources", "arguments": {}}' ``` где: @@ -142,7 +143,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 +159,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..1ee34ff9 100644 --- a/content/documentation/admin/ai-agents/overview.ru.md +++ b/content/documentation/admin/ai-agents/overview.ru.md @@ -1,116 +1,85 @@ --- 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 портала. ## Языковая модель агента -Агент обращается к языковой модели одним из способов: - -- **Собственная модель.** Агент использует свои доступы к модели. AI-провайдер портала ему не нужен. -- **Прокси моделей DDP.** Портал передаёт агенту адрес прокси и короткоживущий токен запуска. Агент обращается к модели через портал, а портал использует [AI-провайдера](../../user/ai-assistant/#подключение-ai-провайдера) пользователя, который запустил задачу, и расходует его квоту. +Агент использует собственные доступы к модели или прокси моделей DDP. При работе через прокси портал использует AI-провайдера пользователя, запустившего задачу, и расходует его квоту. -Платформенный агент всегда работает через прокси моделей 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/#доступные-инструменты). +Например, чтобы агент читал каталог, включите `ddp_get_resources` и `ddp_get_resource_entities` в коллекцию, подключите её к агенту и предоставьте пользователю право использовать её. Для запуска процессов добавьте `get_processes`, `run_process` и `get_process_instance`. -## Токен запуска +Пошаговая настройка — [в руководстве по MCP-коллекциям](../../user/mcp-management/#mcp-коллекции). -На каждый запуск агента портал выпускает токен запуска и передаёт его агенту в метаданных сообщения A2A. -Токен даёт доступ к эндпоинтам `/api/v2/agent-mcp` и `/api/v2/agent-llm` от имени пользователя, который запустил задачу. +## Навыки агента -Токен действует, пока запуск находится в статусе «Выполняется», но не дольше 75 минут. -После завершения или остановки запуска портал отзывает токен, и следующий вызов инструмента или модели агентом завершается ошибкой `401`. +На той же вкладке назначьте [навыки](skills/) с конкретной версией или привязкой «Последняя». При запуске агент получает их названия и описания, полный текст читает через `get_skill` при необходимости. Этот инструмент должен быть доступен через коллекции агента и пользователя. -## Навигация +Для инструкций и материалов в GitLab настройте [источник навыков](skill-sources/). -Агенты настраиваются в разделе «AI» → «AI-агенты»: +## Доступ к агентам -| Пункт меню | Назначение | Разрешение для просмотра | -| --- | --- | --- | -| «Каталог» | Список агентов, подключение внешних агентов, настройка инструментов | `read:ai-agents` | -| «Источники агентов» | [Источники агентов](agent-sources/) из каталога | `read:ai-agents` | -| «История запусков» | [Запуски агентов](runs/) текущего пользователя | `read:ai-agent-runs` | -| «Шаблоны AI-провайдеров» | [Шаблоны AI-провайдеров](provider-templates/) для пользователей портала | `edit:ai-provider-templates` | - -## Разрешения +Использование регулируется глобальным `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..4bc00bff 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-провайдера запускающего пользователя. Для работы с файлами проекта используйте [рабочее пространство](../../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-коллекцию с инструментами `ddp_get_resources` и `ddp_get_resource_entities`. +1. Предоставьте пользователю право использовать эту коллекцию и права чтения нужных объектов каталога. +1. В каталоге агентов откройте редактирование платформенного агента. На вкладке «Инструменты и навыки» выберите коллекцию в «MCP-коллекции» и сохраните. +1. В AI-ассистенте выберите агента и провайдера, затем попросите показать доступные ресурсы каталога. -Агент не хранит доступов к языковой модели: на каждый запуск портал передаёт ему доступ к прокси моделей DDP и AI-провайдера пользователя, который запустил задачу. -Подробнее — в разделе [«Языковая модель агента»](overview/#языковая-модель-агента). +Пустой набор коллекций означает работу без MCP-инструментов. Портал не восстанавливает автоматически прежний набор инструментов чтения. -## Быстрый старт +## Изменение инструментов и навыков -Чтобы пользователи могли работать с платформенным агентом: +Для расширения возможностей отредактируйте коллекцию или подключите другую. Например, для процессов добавьте `get_processes`, `run_process` и `get_process_instance`. Пользователю также необходимы доступ к этим инструментам через коллекции и разрешения на операции с сущностями. -1. Убедитесь, что агент работает. Выполните запрос к эндпоинту состояния портала: +На вкладке «Инструменты и навыки» можно назначить [навыки](skills/). Для их чтения в запуске должен быть доступен `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..d83ffb9c 100644 --- a/content/documentation/admin/ai-agents/provider-templates.ru.md +++ b/content/documentation/admin/ai-agents/provider-templates.ru.md @@ -28,7 +28,7 @@ AI-провайдер нужен пользователю для работы с Чтобы создать шаблон: -1. Перейдите в раздел «AI» → «AI-агенты» → «Шаблоны AI-провайдеров». Раздел доступен с разрешением `edit:ai-provider-templates`. +1. Перейдите в раздел «AI» → «AI-агенты» → «Шаблоны AI-провайдеров». Создание доступно с глобальным `edit:ai-provider-templates`; просмотр и изменение существующих шаблонов также могут быть разрешены объектными ролями. 1. Нажмите «Создать». 1. Заполните поля шаблона, как описано в разделе [«Параметры шаблона»](#параметры-шаблона). 1. Нажмите «Сохранить». @@ -73,12 +73,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/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..4d4fa2f6 --- /dev/null +++ b/content/documentation/admin/ai-agents/skills.ru.md @@ -0,0 +1,111 @@ +--- +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» → «AI-агенты» → «Каталог» и выберите редактирование. +1. На вкладке «Инструменты и навыки» добавьте навык и выберите конкретную версию либо «Последняя». +1. В «MCP-коллекции» подключите коллекцию с инструментом `get_skill`; для чтения дополнительных файлов добавьте также `get_skill_file`. +1. Предоставьте запускающему пользователю доступ к этим инструментам через доступные ему MCP-коллекции. +1. Сохраните агента и начните новый запуск. + +При запуске агент получает названия и описания назначенных навыков и загружает полный текст при необходимости. Без доступного `get_skill` набор навыков не передаётся; форма привязок показывает предупреждение. `list_skills` предназначен для обычного MCP-клиента; агент получает свой подготовленный набор. + +Привязка «Последняя» выбирает активную версию с наибольшим номером при следующем запуске. Закреплённая привязка сохраняет выбранную версию. + +## Подключение к рабочему пространству + +Откройте [шаблон рабочего пространства](../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/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/home/processes.ru.md b/content/documentation/admin/home/processes.ru.md index 360dfa10..7ad8fc28 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` в таком процессе указывает на существующее окружение или систему. diff --git a/content/documentation/admin/overview.ru.md b/content/documentation/admin/overview.ru.md index 9e1699eb..0af7f1ef 100644 --- a/content/documentation/admin/overview.ru.md +++ b/content/documentation/admin/overview.ru.md @@ -5,3 +5,10 @@ weight: 10 --- Руководство администратора Deckhouse Development Portal (DDP) описывает установку портала и настройку его механизмов: источников данных, действий, процессов, виджетов, проверок статуса и других. Руководство входит в состав эксплуатационной документации продукта. + +Для настройки новых сценариев используйте руководства: + +- [Подготовка рабочих пространств](workspaces/overview/): подключения, сеть, хранилище и лимиты. +- [Создание шаблона](workspaces/templates/): проект OpenTofu, параметры, публикация и активация. +- [Файлы и скрипты](workspaces/files/) и [образы, Ingress и хранение](workspaces/network-storage/): примеры изменения стартового шаблона. +- [AI-агенты](ai-agents/overview/) и [навыки](ai-agents/skills/): инструменты и инструкции агентов. diff --git a/content/documentation/admin/processes/overview.ru.md b/content/documentation/admin/processes/overview.ru.md index 67432912..1329eb99 100644 --- a/content/documentation/admin/processes/overview.ru.md +++ b/content/documentation/admin/processes/overview.ru.md @@ -83,7 +83,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 +93,9 @@ description: Создание и запуск процессов — элеме AI-провайдер ищется по названию среди провайдеров пользователя, который запустил процесс: провайдер из шаблона с общим токеном подходит всем, кому разрешён шаблон, а личный провайдер — только его владельцу. Если провайдер не задан в элементе, его можно выбрать при запуске процесса. Без провайдера процесс не запускается и возвращает ошибку «Укажите AI-провайдера на каждом локальном agent-шаге перед запуском процесса». -Агент получает инструменты портала из списка «MCP-инструменты» своего подключения. Если список пуст, агент работает без инструментов портала. +Агент получает инструменты назначенных ему MCP-коллекций, которыми может пользоваться инициатор процесса. Без коллекций агент работает без MCP-инструментов. Для запуска требуется право `use:ai-agents` или `use:ai-agent` на выбранного агента. + +В поле «Исполнитель» можно также выбрать «Рабочее пространство». В этом режиме шаг отправляет задание в прикреплённый чат пространства инициатора, привязанного к сущности процесса. ###### Результат агента diff --git a/content/documentation/admin/security/rbac.ru.md b/content/documentation/admin/security/rbac.ru.md index 40dcc88d..91322620 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` — просмотр и изменение лимитов установки. Внешние сервисы: @@ -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,40 @@ 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`. -- `edit:role-bindings` — редактирование привязок ролей для агента. +Назначенный агенту навык не выдаёт дополнительных разрешений. Чтение навыка в запуске требует инструмента `get_skill`, доступного через MCP-коллекции агента и запускающего пользователя. + +#### Рабочие пространства и шаблоны + +Разрешения можно выдать на отдельный объект: + +| Объект | Разрешения | +| --- | --- | +| Рабочее пространство | `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` и права использования выбранного шаблона. + +Прикрепление к чату и выполнение заданий процесса требуют пространства самого пользователя. Для процесса также необходима привязка к его сущности. Для других объектов (действия, автоматизации, процессы, вебхуки, виджеты, дашборды, внешние сервисы и т. д.): - `read:[object-type]` — просмотр объекта. @@ -528,7 +554,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 +570,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 +579,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/widgets/ai/chat.ru.md b/content/documentation/admin/widgets/ai/chat.ru.md index c4e8ed36..ddfa0aa3 100644 --- a/content/documentation/admin/widgets/ai/chat.ru.md +++ b/content/documentation/admin/widgets/ai/chat.ru.md @@ -21,9 +21,9 @@ weight: 10 | Название вопроса | Да | Короткая подпись, отображаемая на нижней панели виджета и в чате | | Промпт | Да | Инструкция для модели при нажатии на эту кнопку; допускается использование Go-шаблонизации | -При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должен вызвать агент при подготовке ответа. Агент вызывает только инструменты из списка «MCP-инструменты» своего подключения; платформенному агенту также доступны инструменты MCP-коллекций пользователя. +При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должен вызвать агент при подготовке ответа. Агент получает инструменты назначенных ему MCP-коллекций, которыми может пользоваться запускающий пользователь. Без коллекций агент работает без MCP-инструментов. -Инструмент `get_external_data` не входит в базовый набор платформенного агента. Чтобы использовать его в промпте, [добавьте инструмент](../../ai-agents/platform-agent/#добавление-инструментов) платформенному агенту. +Чтобы использовать `get_external_data` в промпте, включите его в [MCP-коллекции агента](../../ai-agents/platform-agent/#изменение-инструментов-и-навыков) и предоставьте пользователю доступ к этому инструменту через коллекцию. Пример промпта для быстрого вопроса: @@ -34,7 +34,7 @@ weight: 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..8a54578a --- /dev/null +++ b/content/documentation/admin/workspaces/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Рабочие пространства +description: Настройка рабочих пространств, их шаблонов и синхронизации из GitLab. +weight: 76 +--- diff --git a/content/documentation/admin/workspaces/files.ru.md b/content/documentation/admin/workspaces/files.ru.md new file mode 100644 index 00000000..ca88cbaf --- /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`, без повышения привилегий и с корневой файловой системой только для чтения. Размещайте рабочие данные на томе и не используйте в скриптах команды, которым нужны права root. Для дополнительных системных пакетов подготовьте собственный образ и укажите его в контейнере шаблона. + +## Применение изменений к существующему пространству + +Чтобы существующее пространство получило новые файлы: + +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..197acd03 --- /dev/null +++ b/content/documentation/admin/workspaces/network-storage.ru.md @@ -0,0 +1,121 @@ +--- +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-хосте. Для домена `ide.example.com` стартовый шаблон создаёт адрес вида `https://ddp-ws-<суффикс>.ide.example.com`. + +Перед запуском подготовьте wildcard-запись `*.ide.example.com`, которая указывает на ingress-контроллер целевого кластера. В `main.tf` задайте: + +```hcl +ide_domain = "ide.example.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` должен находиться в неймспейсе шаблона и содержать сертификат для `*.ide.example.com` с доверенной браузером цепочкой. + +Аннотации в примере предназначены для ingress-nginx и увеличивают тайм-ауты длительных соединений IDE. Для другого контроллера задайте поддерживаемые им аннотации. + +Созданный Ingress направляет трафик в контейнер проверки доступа `gate`, который пропускает сессию, открытую через портал. Сохраняйте этот маршрут при изменении Ingress. Публикация `code-server` напрямую обходит проверку доступа. + +Если ingress-контроллер уже выдаёт подходящий сертификат по умолчанию, задайте `ide_tls_secret = null`. Проверьте, что браузер доверяет сертификату именно для хоста пространства. + +## Выдача сертификата через cert-manager + +При установленном cert-manager и настроенном ClusterIssuer можно получать отдельный сертификат для каждого пространства. Замените значения в `main.tf`: + +```hcl +ide_domain = "ide.example.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..2c186eb9 --- /dev/null +++ b/content/documentation/admin/workspaces/overview.ru.md @@ -0,0 +1,63 @@ +--- +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. Адрес IDE каждого пространства должен быть доступен из браузера пользователя. Порядок настройки — [в примерах Ingress и TLS](network-storage/#публикация-ide). +1. Обеспечьте доступ из целевых подов и Jobs операций к HTTPS-адресу портала с доверенным сертификатом. Он используется для состояния OpenTofu, обращения к модели, MCP и проверки доступа в IDE. +1. Если используются закрытые хранилища образов, подготовьте Secrets для скачивания образов [в соответствующих неймспейсах](network-storage/#образы-из-закрытого-хранилища). +1. Для шаблона с репозиторием создайте подключение Git и заполните реквизиты. Пользователям потребуется [AI-провайдер](../../user/ai-assistant/#подключение-ai-провайдера). + +При установке модулем `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/sources.ru.md b/content/documentation/admin/workspaces/sources.ru.md new file mode 100644 index 00000000..c5916948 --- /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`](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`, затем повторите синхронизацию. + +## Удаление директории или источника + +Удаление директории из выбранной ветки архивирует соответствующий шаблон. Созданные пространства и опубликованные версии сохраняются; новые пространства из архивного шаблона не создаются. Возвращение директории восстанавливает шаблон, если он был архивирован источником. + +Для удаления источника сначала архивируйте его шаблоны. После удаления источника они остаются архивными ручными шаблонами со своими версиями. Данные существующих пространств не удаляются. diff --git a/content/documentation/admin/workspaces/templates.ru.md b/content/documentation/admin/workspaces/templates.ru.md new file mode 100644 index 00000000..f3fcc60d --- /dev/null +++ b/content/documentation/admin/workspaces/templates.ru.md @@ -0,0 +1,131 @@ +--- +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`, например `ide.example.com`, и проверьте [параметры Ingress, TLS, образов и хранения](network-storage/). +1. Нажмите «Сохранить», затем «Опубликовать v1». +1. На вкладке «Версии» нажмите «Активировать v1». + +Пользователь создаёт новое рабочее пространство из активной версии. Опубликованная версия неизменяема; следующая правка выполняется в черновике и публикуется новой версией. + +## Состав стартового проекта + +Файлы определяют объекты Kubernetes и содержимое рабочей директории: + +| Путь | Назначение | +| --- | --- | +| `versions.tf` | Версия OpenTofu, версия и конфигурация провайдера Kubernetes | +| `main.tf` | StatefulSet, постоянный том, Secrets, ConfigMap, Service, Ingress и настройки доставки файлов | +| `variables.tf` | Пользовательские параметры формы создания | +| `outputs.tf` | Обязательный результат `ddp_runtime` | +| `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"`. Стартовый проект возвращает: + +```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 + } +} +``` + +Портал использует StatefulSet для запуска и остановки, контейнер агента и его порт для заданий, адрес `ide_url` для открытия IDE. Сохраняйте соответствие результата фактически созданным объектам и HTTPS-адресу IDE при изменении шаблона. + +## Навыки и архивирование + +На вкладке «Навыки» выберите [навыки DDP](../ai-agents/skills/) и закреплённую версию либо «Последняя». Набор фиксируется при создании и каждом запуске рабочего пространства. + +Для шаблона с Git переключатель «Разрешить навыки из репозитория» задаёт доступность навыков самой рабочей копии. Если он выключен, выбранные «Скрытые директории навыков» исключаются из рабочей копии при запуске. Это ограничение видимости файлов; прочитать их через Git всё ещё возможно. + +Архивный шаблон сохраняет версии и существующие рабочие пространства, но новые пространства из него создавать нельзя. Для возобновления создания используйте «Вернуть из архива». + +## Ограничения файлов + +При редактировании учитывайте ограничения шаблона: + +| Ограничение | Значение | +| --- | --- | +| Число файлов | До 256 | +| Размер одного файла | До 1 МиБ | +| Содержимое | Текст в UTF-8 | +| Путь | Относительный, без пустых сегментов, `.` и `..` | + +Практические примеры — [доставка файлов и скрипты](files/), [образы, Ingress и хранение](network-storage/), [синхронизация из GitLab](sources/). 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..08311b87 100644 --- a/content/documentation/release-notes/v1.8.0.ru.md +++ b/content/documentation/release-notes/v1.8.0.ru.md @@ -1,55 +1,44 @@ --- 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-агенты). +- Прежние списки инструментов агентов и источников не переносятся: назначьте [MCP-коллекции](../user/mcp-management/#связь-с-ai-ассистентом-и-mcp-сервером) заново. Это относится и к встроенным инструментам. +- Часть прежних имён MCP-инструментов заменена именами операций API с префиксом `ddp_`. Обновите [интеграции и инструкции агентов](../user/mcp-server/#инструменты-операций-api). +- Форма сущности проверяет [обязательные параметры](../user/properties/#конфигурация); окна запуска также требуют обязательные значения типов Users, Teams и Object. -## Улучшения - -### Каталог +## Новые возможности -- Новая [страница сущности](../user/catalog/#страница-сущности): описание, команда и владелец под заголовком, блоки «Параметры», «Запуск» и «Связи» на вкладке «Обзор». -- В [списке сущностей](../user/catalog/#список-сущностей) появились фильтры по статусу и команде-владельцу. +Добавлены возможности работы с проектами и AI: -### Параметры +- [Рабочие пространства](../user/workspaces/) создаются из шаблона, открываются в IDE и выполняют задания из чата. +- [Шаблоны рабочих пространств](../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, навыков и рабочих пространств. -Элемент параметра типа [«Array»](../user/properties/#array) задаётся текстом или JSON. +## Улучшения -### Процессы +Изменены пользовательские сценарии каталога и процессов: -- У задачи, шага «AI-агент» и параллельного шлюза появилось поле «Таймаут (секунды)». Без значения шаг ждёт 60 минут и получает статус `Timeout`. Подробнее — в разделе [«Задача»](../admin/processes/overview/#задача). -- Схема нового процесса настраивается сразу при создании: вкладки «Конфигурация» и «Параметры» доступны до первого сохранения, процесс открывается со схемой «Начало → Конец». +- Обновлена [страница сущности](../user/catalog/#страница-сущности); в списке доступны фильтры по статусу и команде. +- Для задач, AI-шагов и параллельных шлюзов процессов настраивается [тайм-аут](../admin/processes/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/). +- Переключение чатов во время ответа агента больше не смешивает сообщения разных диалогов. +- Записи действий больше не остаются выполняющимися после удаления связанной сущности. diff --git a/content/documentation/user/ai-assistant.ru.md b/content/documentation/user/ai-assistant.ru.md index e36e2e0b..d07bb564 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-ассистентом требуется доступ хотя бы к одному включённому агенту: глобальное `use:ai-agents` или объектное `use:ai-agent`. Владение даёт права при включённом `owner-is-admin`. ## Подключение AI-провайдера @@ -126,8 +127,7 @@ Authorization: Bearer {{ .token }} ### Инструменты MCP -Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Набор инструментов агента задаёт администратор в поле «MCP-инструменты» подключения агента. -Платформенному агенту в AI-ассистенте также доступны пользовательские инструменты из [MCP-коллекций](../mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. +Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Набор задают [MCP-коллекции](mcp-management/#mcp-коллекции) на вкладке «Инструменты и навыки» подключения агента. В запуск попадают инструменты этих коллекций, которыми может пользоваться запускающий пользователь. Это правило распространяется и на платформенного агента; без коллекций агент работает без MCP-инструментов. Кнопка «Инструменты» в окне ассистента открывает список инструментов с типом (`internal`, `external`, `custom`), числом аргументов и примером запроса. Кнопка «В поле ввода» вставляет пример в поле ввода. @@ -136,6 +136,20 @@ Authorization: Bearer {{ .token }} - Встроенные инструменты (`internal`) и их параметры описаны в [документации MCP-сервера](../mcp-server/). - Подключение MCP-серверов, пользовательских MCP-инструментов и настройка коллекций — в разделе [«Управление MCP»](../mcp-management/). +## Работа с проектом + +Для задач с файлами прикрепите [рабочее пространство](workspaces/) кнопкой «Прикрепить рабочее пространство». В этом режиме отвечает OpenCode пространства; IDE и чат используют одну рабочую копию. Настройки подтверждений и очереди описаны [в руководстве по чату рабочего пространства](workspace-chat/). + +Если агенту из каталога доступны `get_workspace_templates`, `create_workspace`, `get_workspace` и `attach_workspace`, можно попросить его подготовить пространство прямо из чата. Например: + +```text +Создай рабочее пространство из шаблона team-development для https://gitlab.example.com/team/service.git на 8 часов и прикрепи его к этому чату. После запуска добавь тест обработчика /healthz. +``` + +Агент получает параметры шаблона, создаёт пространство с правами пользователя и прикрепляет его после готовности. Попросите администратора выдать нужные инструменты и доступ к шаблону, если сценарий недоступен. + +Кнопка «Моя статистика» открывает [личные показатели использования AI](ai-statistics/). + ## Устранение неполадок Типовые ошибки AI-ассистента: @@ -144,7 +158,7 @@ Authorization: Bearer {{ .token }} | --- | --- | | «Для вашей учётной записи не настроен AI-провайдер. Добавьте его в настройках профиля.» | У пользователя нет AI-провайдера. Подключите провайдера, как описано в разделе [«Подключение AI-провайдера»](#подключение-ai-провайдера) | | «Выберите AI-провайдера» | Для выбранного агента нужен провайдер. Выберите провайдера в поле «Провайдер» | -| «Недостаточно прав для запуска этого AI-агента» | У пользователя нет разрешения `run:ai-agents` или выбран внешний агент, владельцем которого пользователь не является | +| «Недостаточно прав для запуска этого AI-агента» | Нет глобального `use:ai-agents` или объектного `use:ai-agent` на выбранного агента; проверьте роль и доступ к агенту | | «LLM-провайдер отклонил запрос. Проверьте API-ключи в настройках профиля.» | Провайдер не принял токен. Проверьте токен и заголовки провайдера | | «Превышен лимит запросов к LLM-провайдеру. Попробуйте позже.» | Провайдер ограничил число запросов | diff --git a/content/documentation/user/ai-statistics.ru.md b/content/documentation/user/ai-statistics.ru.md new file mode 100644 index 00000000..1910bda9 --- /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 | Приближённые значения длительности по группам измерений; незавершённые операции в них не входят | +| Навык «Подключён» | Был назначен агенту или рабочему пространству; это не означает, что агент его прочитал | +| Навык «Использован» | Агент прочитал навык через `get_skill` либо инструмент навыков рабочего пространства | +| Навык «нет в каталоге» | Навык удалён или прочитан не из каталога DDP | +| Рабочие пространства у навыка | Сумма по дням пространств с заданиями; одно пространство может учитываться в разные дни | +| «По TTL» | Остановка рабочего пространства по истечении срока работы | + +Статистика использования не заменяет расчёт стоимости у провайдера. Если провайдер не возвращает отчёт о токенах, число запросов и число запросов с отчётом могут различаться. + +## Хранение данных + +При установке модулем срок хранения суточных агрегатов задаётся в ModuleConfig, в `spec.settings.ai.statistics.retentionDays`. По умолчанию — 365 дней. Пример изменения срока: + +```yaml +ai: + statistics: + retentionDays: 180 +``` + +Агрегаты старше срока удаляются раз в час. Срок хранения подробных журналов запусков и MCP-вызовов задаётся отдельно; сохранённая статистика может оставаться после удаления подробных записей. diff --git a/content/documentation/user/interface.ru.md b/content/documentation/user/interface.ru.md index 6be3c4cc..5126e1f2 100644 --- a/content/documentation/user/interface.ru.md +++ b/content/documentation/user/interface.ru.md @@ -1,14 +1,15 @@ --- title: Интерфейс +description: Разделы DDP, верхняя панель и поиск сущностей каталога. weight: 20 --- Интерфейс Deckhouse Development Portal (DDP, портал) состоит из следующих разделов: -- «Главная» — рабочее пространство разработчиков: команды, системы, микросервисы, окружения, развёртывание и заказ ресурсов. Вкладка отображается, если главная включена администратором. Подробнее — в разделе [«Главная»](home/overview/). +- «Главная» — страница разработчика: команды, системы, микросервисы, окружения, развёртывание и заказ ресурсов. Вкладка отображается, если главная включена администратором. Подробнее — в разделе [«Главная»](home/overview/). - «Каталог» — сервисный каталог для просмотра ресурсов, сущностей и связей, а также для запуска действий и сценариев. - «Самообслуживание» — раздел для настройки источников данных, действий, вебхуков, автоматизаций, сценариев, дашбордов и виджетов. Доступ к разделу может быть ограничен ролевой моделью. -- «AI» — раздел для настройки MCP-серверов, пользовательских инструментов и коллекций инструментов. Подробнее — в разделе [«Управление MCP»](mcp-management/). Доступ к разделу может быть ограничен ролевой моделью. +- «AI» — раздел рабочих пространств, навыков, агентов, AI-провайдеров, MCP-инструментов и статистики использования. Подробнее — в разделе [«Управление MCP»](mcp-management/). Доступ к разделу может быть ограничен ролевой моделью. - «Администрирование» — раздел для управления командами, пользователями, политиками доступа и учётными данными. Доступ к разделу может быть ограничен ролевой моделью. ## Верхняя панель diff --git a/content/documentation/user/mcp-management.ru.md b/content/documentation/user/mcp-management.ru.md index 101bf20b..a4be4354 100644 --- a/content/documentation/user/mcp-management.ru.md +++ b/content/documentation/user/mcp-management.ru.md @@ -22,23 +22,51 @@ 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,7 +81,7 @@ 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 +94,32 @@ 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. В составе коллекции нажмите «Добавить в коллекцию» и выберите отдельные инструменты `ddp_get_resources` и `ddp_get_resource_entities`. 1. Нажмите «Сохранить». +1. В меню коллекции выберите «Настроить доступ» и выдайте пользователям или командам роль с `use:mcp-collections`. + +Пользователь сможет вызывать эти инструменты из MCP-клиента с собственным API-токеном. Для агента дополнительно [подключите коллекцию к агенту](#связь-с-ai-ассистентом-и-mcp-сервером). Права на чтение ресурсов и сущностей каталога предоставляются отдельно. + +### Группы и серверы целиком + +В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», или «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. + +Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией. -Чтобы пользователь мог вызывать инструменты коллекции, откройте меню карточки коллекции и выберите «Настроить доступ». Назначьте пользователям или командам роль с разрешением `use:mcp-collections`. Список разрешений приведён в [ролевой модели](../../admin/security/rbac/#mcp-коллекции). +Если набор должен оставаться фиксированным, добавляйте отдельные инструменты. Группы могут включать операции изменения и удаления данных; проверяйте их состав перед выдачей доступа. -Владелец коллекции и супер-администратор получают доступ к коллекции автоматически. +### Доступ и включение + +Выключенная коллекция не предоставляет инструменты. Владение коллекцией и участие в её команде дают права при включённой настройке `owner-is-admin`; доступ остальных пользователей задаётся ролями. Супер-администратор имеет доступ ко всем коллекциям. ## Каталог @@ -86,8 +127,22 @@ MCP-коллекция объединяет инструменты из ката ## Связь с AI-ассистентом и MCP-сервером -Инструменты из MCP-коллекций используются следующим образом: +Чтобы выдать инструменты агенту: + +1. Откройте редактирование агента в «AI» → «AI-агенты» → «Каталог». +1. На вкладке «Инструменты и навыки» выберите «MCP-коллекции» и сохраните. +1. Убедитесь, что запускающему пользователю разрешены нужные инструменты через доступные ему коллекции. +1. Выдайте пользователю право использовать агента и необходимые права на объекты портала. +1. Запустите новый диалог или задание и проверьте вызов инструмента. + +Набор инструментов запуска — пересечение инструментов коллекций агента и инструментов, доступных запускающему пользователю. Пользователь может получать тот же инструмент через другую коллекцию; совпадение самой коллекции не требуется. + +Без коллекций агент работает без MCP-инструментов. Правило действует для платформенного и внешних агентов в ассистенте, виджете и процессе. Для агента из источника коллекции задаёт источник. + +[Внешний MCP-клиент](mcp-server/) использует коллекции своего пользователя; привязка к агенту для него не требуется. [Рабочее пространство](workspaces/) вызывает MCP от имени владельца и использует его доступ к инструментам. + +## Настройка после обновления + +При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам. -- В [AI-ассистенте](../ai-assistant/#инструменты-mcp) по кнопке «Инструменты» отображаются встроенные инструменты и инструменты из доступных коллекций. Платформенный агент в AI-ассистенте может вызывать инструменты из доступных пользователю коллекций; внешний агент — только инструменты из списка «MCP-инструменты» своего подключения. -- [AI-агенты](../admin/ai-agents/overview/#инструменты-агента) в шагах процессов вызывают только инструменты из списка «MCP-инструменты» своего подключения. -- [MCP-сервер](../mcp-server/) портала возвращает и вызывает те же инструменты из коллекций, которые доступны пользователю с учётом его прав RBAC. +Часть прежних встроенных инструментов заменена [операциями с префиксом `ddp_`](mcp-server/#инструменты-операций-api). Обновите состав коллекций, сохранённые запросы MCP-клиентов и инструкции навыков. Для навыков агента проверьте доступность `get_skill`. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 65af384e..68a3ec5b 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -13,105 +13,44 @@ 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 с префиксом `ddp_` и специализированные инструменты, перечисленные ниже. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. -### get_resources +### Инструменты операций API -Получить список ресурсов. +Имя инструмента операции имеет вид `ddp_`. В «AI» → «MCP» → «Каталог» доступны описание операции и схема её аргументов. Инструменты объединены в группы, например «Каталог», «Действия», «Процессы и автоматизации» и «Рабочие пространства». -Параметры: нет. +Примеры замены прежних имён: -Возвращает: список ресурсов. +| Прежнее имя | Актуальный инструмент | +| --- | --- | +| `get_resources` | `ddp_get_resources` | +| `get_resource_entities` | `ddp_get_resource_entities` | +| `get_entity` | `ddp_get_entity` | +| `get_entity_relations` | `ddp_get_entity_relations` | +| `get_actions` | `ddp_get_actions` | +| `get_datasources` | `ddp_get_datasources` | +| `get_external_services` | `ddp_get_external_services` | +| `get_process_instances` | `ddp_get_entity_process_history` | -Пример: - -```text -Получи список ресурсов -``` - ---- - -### get_external_services +При переносе интеграции обновите имя и прочитайте `inputSchema` из `tools/list`: аргументы соответствуют операции API и могут отличаться от прежнего инструмента. Специализированные `get_processes`, `run_process` и `get_process_instance` сохраняют собственные имена и параметры. -Получить список внешних сервисов (GitLab, SonarQube и т. д.). +Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например: -Параметры: нет. - -Возвращает: список внешних сервисов. - -Пример: - -```text -Получи список внешних сервисов -``` - ---- - -### get_resource_entities - -Получить все сущности выбранного ресурса. - -Параметры: - -| Название | Тип | Обязательность | Описание | -|------------------|--------|----------------|---------------| -| `resource_uuid` | строка | Да | UUID ресурса | - -Возвращает: список сущностей ресурса. - -Пример: - -```text -Получи все сервисы и покажи название и дату создания -``` - ---- - -### get_entity - -Получить одну сущность по UUID. - -Параметры: - -| Название | Тип | Обязательность | Описание | -|-----------------|--------|----------------|---------------| -| `entity_uuid` | строка | Да | UUID сущности | - -Возвращает: данные одной сущности. - -Пример: - -```text -Получи сущность с UUID 3fa85f64-5717-4562-b3fc-2c963f66afa6 -``` - ---- - -### get_entity_relations - -Получить связи сущности. - -Параметры: - -| Название | Тип | Обязательность | Описание | -|------------------|--------|----------------|------------------------| -| `resource_uuid` | строка | Да | UUID ресурса | -| `entity_slug` | строка | Да | Идентификатор сущности | - -Возвращает: список связей сущности. - -Пример: - -```text -Получи связи сущности «api-gateway» ресурса «Сервисы» +```json +{ + "status": 200, + "contentType": "application/json; charset=utf-8", + "encoding": "json", + "body": [] +} ``` ---- +Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Проверяйте `status` и тело ответа, в том числе при отказе в доступе и ошибках проверки входных данных. ### get_external_data @@ -139,40 +78,6 @@ MCP — это открытый протокол для взаимодейств --- -### get_actions - -Получить список действий с описанием входных параметров. - -Параметры: нет. - -Возвращает: для каждого действия — UUID, идентификатор, название, описание, тип, признак подтверждения `approval`, привязанные ресурсы и параметры пользовательской формы. Для параметров типов Enum и List возвращаются варианты значений. Тело действия и настройки запроса не возвращаются. - -Действие с `approval: true` при запуске ожидает подтверждения. - -Пример: - -```text -Получи список действий -``` - ---- - -### get_datasources - -Получить список источников данных. - -Параметры: нет. - -Возвращает: список источников данных. - -Пример: - -```text -Получи список источников данных -``` - ---- - ### get_processes Получить список процессов с параметрами запуска. @@ -242,49 +147,52 @@ MCP — это открытый протокол для взаимодейств --- -### get_process_instances +### get_process_instance -Получить запуски процессов сущности, новые первыми. +Получить один запуск процесса с хранилищем. Параметры: | Название | Тип | Обязательность | Описание | |---|---|---|---| | `entity_uuid` | строка | Да | UUID сущности | -| `process_uuid` | строка | Нет | Вернуть только запуски этого процесса | -| `status` | строка | Нет | Вернуть только запуски с этим статусом, например `Running` или `Completed` | -| `page` | число | Нет | Номер страницы, начиная с 1 | -| `per_page` | число | Нет | Число запусков на странице. По умолчанию — 10 | +| `instance_uuid` | строка | Да | UUID запуска процесса из `ddp_get_entity_process_history` или из ответа `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/) передают инструкции и дополнительные файлы: -Получить один запуск процесса с хранилищем. +| Инструмент | Аргументы | Результат | +| --- | --- | --- | +| `list_skills` | Необязательная строка `q` | Доступные пользователю навыки с описаниями и последними версиями | +| `get_skill` | Обязательный `name`, необязательный `version` | Текст `SKILL.md`, версия и список файлов | +| `get_skill_file` | Обязательные `name` и `path`, необязательный `version` | Текст дополнительного файла | -Параметры: +В обычном MCP-клиенте версия выбирается меткой; без неё используется последняя активная. В запуске агента доступ ограничен назначенными ему навыками и зафиксированными версиями. Бинарные файлы и файлы больше 1 МиБ через `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/) из чата: -Пример: +| Инструмент | Аргументы | Результат | +| --- | --- | --- | +| `get_workspace_templates` | Нет | Доступные шаблоны с активной версией, настройками репозитория и параметрами | +| `create_workspace` | Обязательные `template_uuid`, `name`, `ttl_hours`; необязательные `provider`, `repository_url`, `base_ref`, `entity_uuid`, `parameters` | Состояние созданного пространства; операция выполняется асинхронно | +| `get_workspace` | Обязательный `workspace_uuid`, необязательный `wait_seconds` до 45 | Статус, готовность, последняя ошибка и активная операция | +| `attach_workspace` | Обязательный `workspace_uuid` | Прикрепление пространства к текущему чату | -```sh -Покажи результат экземпляра процесса 3fa85f64-5717-4562-b3fc-2c963f66afa6 -``` +`provider` можно не передавать, когда подходящий провайдер уже задан в контексте чата. При вызове вне такого контекста укажите его явно. `parameters` — объект значений переменных шаблона; `ttl_hours` — целое число от 1 до 720. + +`attach_workspace` работает только в контексте агента, отвечающего в чате портала. Используйте последовательность: получить шаблоны, создать пространство, дождаться готовности, прикрепить его к чату. ## Подключение MCP-сервера @@ -353,7 +261,7 @@ Content-Type: application/json "id": 1, "method": "tools/call", "params": { - "name": "get_resource_entities", + "name": "ddp_get_resource_entities", "arguments": { "resource_uuid": "" } @@ -388,7 +296,7 @@ Content-Type: application/json Права доступа: - Инструменты работают с теми же правами, что и пользователь. -- Инструменты `run_process` и `get_external_data` изменяют данные: первый запускает процесс, второй может выполнить запрос `POST`, `PUT`, `PATCH` или `DELETE` к внешнему сервису. +- `run_process`, `create_workspace`, `attach_workspace` и изменяющие операции `ddp_*` выполняют действия от имени пользователя. `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/workspace-chat.ru.md b/content/documentation/user/workspace-chat.ru.md new file mode 100644 index 00000000..84deb2a3 --- /dev/null +++ b/content/documentation/user/workspace-chat.ru.md @@ -0,0 +1,51 @@ +--- +title: Чат рабочего пространства +description: Задания AI-агенту рабочего пространства, подтверждения действий, очередь сообщений, изменения файлов и контекст. +weight: 56 +--- + +Прикреплённое [рабочее пространство](workspaces/) переводит чат AI-ассистента на агента OpenCode этого пространства. Агент получает доступ к рабочим файлам и терминалу. Выбранный для обычного чата агент из каталога в этом режиме не выполняет задачу. + +## Начало работы + +Чтобы продолжить работу с проектом в чате: + +1. Создайте и запустите рабочее пространство. +1. Откройте его карточку и нажмите «Открыть чат». Для существующего чата используйте кнопку «Прикрепить рабочее пространство» в AI-ассистенте. +1. Проверьте прикреплённое пространство и отправьте задачу. +1. Во время выполнения отвечайте на вопросы и запросы подтверждения агента. +1. Проверьте итоговый ответ и изменения файлов. + +Чат и IDE используют одну рабочую копию. Открывайте IDE для просмотра и редактирования файлов, запуска тестов и работы с Git. + +## Подтверждения действий + +В чате предусмотрены режимы «Автоматически» и «Подтверждать». Во втором режиме агент запрашивает разрешение на действия, которые требуют подтверждения, например выполнение команды. + +Для каждого запроса проверьте действие и выберите «Разрешить», «Отклонить» или «Разрешать всегда в этом рабочем пространстве». Разовое разрешение действует на текущий запрос. Постоянное разрешение сохраняет правило для последующих совпадающих запросов во всех чатах пространства; его можно удалить через «Разрешено всегда». При отказе комментарий задаёт агенту, что сделать вместо действия; отказ без комментария останавливает задание. + +Навык может содержать инструкции и скрипты, но сам по себе не предоставляет новых прав на объекты портала. Инструменты MCP выполняются с правами владельца рабочего пространства. + +## Очередь и остановка + +Пока агент отвечает, следующие сообщения попадают в очередь. Можно забрать ожидающее сообщение из очереди до начала его выполнения. + +Кнопка остановки прерывает текущее задание агента. Чтобы остановить также 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..064f96df --- /dev/null +++ b/content/documentation/user/workspaces.ru.md @@ -0,0 +1,102 @@ +--- +title: Рабочие пространства +description: Создание рабочего пространства с IDE и AI-агентом, работа с репозиторием, остановка, обновление и диагностика. +weight: 55 +--- + +Рабочее пространство — персональная IDE и AI-агент OpenCode в Kubernetes. Агент читает и изменяет файлы, выполняет команды и отвечает в прикреплённом чате. IDE и чат работают с одними файлами; после остановки данные сохраняются на постоянном томе. + +Администратор подготавливает [шаблон рабочего пространства](../admin/workspaces/templates/), который задаёт кластер, репозиторий, инструменты и параметры запуска. Рабочее пространство можно создать с репозиторием или с пустой рабочей директорией, если это предусмотрено шаблоном. + +## Создание рабочего пространства + +Перед созданием подключите [AI-провайдера](ai-assistant/#подключение-ai-провайдера). Если шаблон использует личные реквизиты, заполните в профиле [учётные данные](credentials/) для его подключений Kubernetes и Git. + +Чтобы создать рабочее пространство: + +1. Откройте «AI» → «Рабочие пространства» и нажмите «Создать рабочее пространство». +1. На шаге «Шаблон» выберите шаблон. Для обычного запуска используйте активную опубликованную версию. +1. Укажите «Название». Если шаблон разрешает выбор репозитория, заполните «URL репозитория» и при необходимости «Ветка или тег». Пустая ветка означает основную ветку репозитория. URL должен использовать HTTPS и относиться к подключению Git шаблона. +1. При необходимости выберите «Ресурс сущности» и «Сущность каталога». Привязка задаётся при создании; она нужна, чтобы процессы сущности могли выполнять задания в этом рабочем пространстве. +1. На шаге «Параметры шаблона» заполните обязательные параметры и проверьте значения по умолчанию. +1. На шаге «Ассистент и срок» выберите «AI-провайдер» и «Срок работы», затем нажмите «Создать». +1. Дождитесь статуса «Работает». Подробности создания доступны на вкладке «Операции». + +Если доступных шаблонов нет, попросите администратора опубликовать и активировать версию шаблона и выдать доступ к нему. Создание также требует настроенных лимитов установки и разрешения `create:workspaces`. + +## Работа в IDE + +Откройте карточку работающего рабочего пространства и нажмите «Открыть IDE». Разрешите браузеру открыть новую вкладку. + +IDE открывается на отдельном HTTPS-домене. Вход проверяет портал; для повторного входа после истечения сессии используйте кнопку «Открыть IDE». Рабочая директория штатного шаблона — `/workspace/code`. + +В терминале IDE команда `opencode` подключается к тому же агенту, который отвечает в чате портала. Изменения файлов видны в IDE и в чате. Для сохранения результата в Git проверьте изменения, создайте коммит и отправьте его в репозиторий. + +## Задание агенту в чате + +Чтобы агент изменил проект: + +1. В карточке рабочего пространства нажмите «Открыть чат» или прикрепите пространство в AI-ассистенте кнопкой «Прикрепить рабочее пространство». +1. Убедитесь, что чат показывает прикреплённое рабочее пространство. +1. Отправьте задачу с ожидаемым результатом, например: + + ```text + Изучи проект, добавь проверку /healthz и тест для неё. Запусти связанные тесты и покажи изменённые файлы. Коммит не создавай. + ``` + +1. Проверьте ответ, выполненные команды и изменения файлов. История заданий доступна также на вкладке «Задания» карточки пространства. + +Одновременно в рабочем пространстве выполняется одно задание. Следующие сообщения ожидают в очереди. Остановка ответа прерывает текущее задание; само рабочее пространство продолжает работать. + +Режим подтверждений задаёт, выполняет ли агент действия автоматически или запрашивает разрешение. В режиме с подтверждениями ответьте на запрос в чате; сохранённое разрешение на повторяющееся действие можно отозвать. Подробности — [в руководстве по чату рабочего пространства](workspace-chat/). + +## Остановка и срок работы + +Для остановки нажмите «Остановить» и подтвердите действие. IDE и текущее задание прерываются, файлы и состояние на постоянном томе сохраняются. + +«Срок работы» задаётся от 1 до 720 часов. По истечении срока портал останавливает рабочее пространство автоматически. Остановленные пространства не занимают места в лимите запущенных пространств; их постоянные тома продолжают занимать хранилище. + +Для продолжения нажмите «Запустить». При запуске штатный шаблон сохраняет существующую рабочую копию Git; повторное клонирование не выполняется. Изменения в удалённом репозитории получите обычными командами Git. + +## Обновление шаблона + +Публикация новой активной версии шаблона не обновляет существующие рабочие пространства автоматически. + +Чтобы применить новую версию: + +1. Остановите рабочее пространство. +1. Нажмите «Обновить версию». +1. Выберите версию и проверьте параметры. Форма отмечает новые, удалённые и изменённые значения. +1. Подтвердите обновление и проверьте его результат на вкладке «Операции». +1. После успешного обновления запустите рабочее пространство. + +Данные постоянных томов сохраняются. Изменение шаблона, которое удаляет или заменяет существующий постоянный том, отклоняется. Файлы, которыми управляет шаблон, при следующем запуске обновляются по [политике доставки файлов](../admin/workspaces/files/). + +## Диагностика + +Сначала откройте карточку пространства и найдите последнюю операцию с ошибкой. Используйте подходящую вкладку: + +| Вкладка | Что проверить | +| --- | --- | +| «Операции» | Вывод OpenTofu при создании, запуске, обновлении или удалении | +| «Диагностика» | Состояние StatefulSet, пода, контейнеров и постоянных томов, события Kubernetes, текущие и предыдущие логи контейнеров | +| «Задания» | Статус задания, вызовы инструментов и ошибки агента | + +Типовые причины и действия: + +| Симптом | Действие | +| --- | --- | +| Не удаётся клонировать репозиторий | Проверьте URL и токен Git той учётной записи, которую использует шаблон | +| Под не скачивает образ | Попросите администратора проверить `image_pull_secrets` шаблона и Secrets в целевом неймспейсе | +| Постоянный том не готов | Проверьте с администратором класс хранения и доступный объём | +| Ошибка контейнера `bootstrap` | Прочитайте его лог; проверьте файлы и скрипты шаблона | +| IDE не открывается при работающем поде | Проверьте с администратором DNS, TLS и Ingress отдельного домена IDE | +| Достигнут лимит запущенных пространств | Остановите ненужное пространство или попросите администратора изменить лимит | + +После устранения причины используйте «Повторить» у неуспешной операции. Для повторения требуются права на соответствующую операцию. + +## Удаление + +Перед удалением отправьте нужные изменения в Git или скопируйте файлы из IDE. Нажмите «Удалить» и подтвердите действие. + +Удаление уничтожает объекты рабочего пространства в Kubernetes и постоянные данные. Остановка подходит для перерыва в работе, удаление — для окончательного освобождения ресурсов.