From aea90bcb6491322dbd3880f11d38994d61eda6a1 Mon Sep 17 00:00:00 2001 From: Nikita Velgin Date: Thu, 29 Oct 2026 12:28:45 +0300 Subject: [PATCH 1/2] docs: renew ai docs --- .../admin/ai-agents/external-agents.ru.md | 4 +- .../admin/ai-agents/overview.ru.md | 8 +- .../admin/ai-agents/platform-agent.ru.md | 6 +- .../admin/ai-agents/skills.ru.md | 6 +- .../documentation/admin/security/rbac.ru.md | 4 +- .../documentation/admin/widgets/ai/chat.ru.md | 4 +- .../documentation/admin/workspaces/apps.ru.md | 108 ++++++++++++++ .../admin/workspaces/network-storage.ru.md | 16 ++- .../admin/workspaces/overview.ru.md | 2 +- .../admin/workspaces/sources.ru.md | 4 +- .../admin/workspaces/templates.ru.md | 21 ++- .../documentation/release-notes/v1.8.0.ru.md | 7 +- content/documentation/user/ai-assistant.ru.md | 4 +- .../documentation/user/ai-statistics.ru.md | 2 +- .../documentation/user/catalog-explorer.ru.md | 135 ++++++++++++++++++ .../documentation/user/mcp-management.ru.md | 8 +- content/documentation/user/mcp-server.ru.md | 79 +++++----- content/documentation/user/workspaces.ru.md | 35 +++++ 18 files changed, 385 insertions(+), 68 deletions(-) create mode 100644 content/documentation/admin/workspaces/apps.ru.md create mode 100644 content/documentation/user/catalog-explorer.ru.md diff --git a/content/documentation/admin/ai-agents/external-agents.ru.md b/content/documentation/admin/ai-agents/external-agents.ru.md index da56ae6..560e340 100644 --- a/content/documentation/admin/ai-agents/external-agents.ru.md +++ b/content/documentation/admin/ai-agents/external-agents.ru.md @@ -97,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": "ddp_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": "get_resources", "arguments": {}}' ``` где: @@ -107,6 +107,8 @@ curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-T Инструмент, которого нет в `ddp.mcp.toolAllowlist`, возвращает ошибку `403`. Недействительный или отозванный токен — ошибку `401`. +Этот эндпоинт принимает имена из списка инструментов без префикса агента: `get_resources`, `query_catalog`, `curated_get_skill`. Префикс `ddp_` платформенный агент добавляет только при передаче инструментов модели. При реализации внешнего агента сохраняйте соответствие между именем для модели и именем, отправляемым порталу. + ### Обращение к модели через портал Если агенту разрешён прокси моделей DDP, он обращается к `/chat/completions` как к API OpenAI Chat Completions и передаёт `ddp.llm.apiKey` как API-ключ. diff --git a/content/documentation/admin/ai-agents/overview.ru.md b/content/documentation/admin/ai-agents/overview.ru.md index 79dab5c..2d20d4d 100644 --- a/content/documentation/admin/ai-agents/overview.ru.md +++ b/content/documentation/admin/ai-agents/overview.ru.md @@ -42,13 +42,17 @@ AI-агент получает задачу на естественном язы Без коллекций агент работает без MCP-инструментов. Это правило одинаково для платформенного агента, внешних агентов, чата, виджетов и процессов. Состав коллекции может включать инструменты портала, подключённых MCP-серверов и пользовательские HTTP-инструменты. -Например, чтобы агент читал каталог, включите `ddp_get_resources` и `ddp_get_resource_entities` в коллекцию, подключите её к агенту и предоставьте пользователю право использовать её. Для запуска процессов добавьте `get_processes`, `run_process` и `get_process_instance`. +Например, чтобы агент читал каталог, включите `get_resources` и `get_resource_entities` в коллекцию, подключите её к агенту и предоставьте пользователю право использовать её. Для запуска процессов добавьте `curated_get_processes`, `curated_run_process` и `curated_get_process_instance`. Пошаговая настройка — [в руководстве по MCP-коллекциям](../../user/mcp-management/#mcp-коллекции). +Для поиска, подсчёта и группировки сущностей, анализа связей и диагностики процессов подключите группу «Обозреватель каталога». Настройка и примеры — [в руководстве по обозревателю](../../user/catalog-explorer/). + +В коллекциях используются имена `get_resources`, `curated_run_process` и `curated_get_skill`. В инструкциях платформенному агенту добавляйте префикс `ddp_`: `ddp_get_resources`, `ddp_curated_run_process`, `ddp_curated_get_skill`. Полная [схема имён инструментов](../../user/mcp-server/#имена-инструментов) учитывает и вызовы из внешнего MCP-клиента. + ## Навыки агента -На той же вкладке назначьте [навыки](skills/) с конкретной версией или привязкой «Последняя». При запуске агент получает их названия и описания, полный текст читает через `get_skill` при необходимости. Этот инструмент должен быть доступен через коллекции агента и пользователя. +На той же вкладке назначьте [навыки](skills/) с конкретной версией или привязкой «Последняя». При запуске агент получает их названия и описания, полный текст читает через `curated_get_skill` при необходимости. Этот инструмент должен быть доступен через коллекции агента и пользователя. Для инструкций и материалов в GitLab настройте [источник навыков](skill-sources/). diff --git a/content/documentation/admin/ai-agents/platform-agent.ru.md b/content/documentation/admin/ai-agents/platform-agent.ru.md index 089d843..5096d1a 100644 --- a/content/documentation/admin/ai-agents/platform-agent.ru.md +++ b/content/documentation/admin/ai-agents/platform-agent.ru.md @@ -14,7 +14,7 @@ description: Подготовка платформенного агента ddp- 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. Создайте включённую MCP-коллекцию с инструментами `get_resources` и `get_resource_entities`. 1. Предоставьте пользователю право использовать эту коллекцию и права чтения нужных объектов каталога. 1. В каталоге агентов откройте редактирование платформенного агента. На вкладке «Инструменты и навыки» выберите коллекцию в «MCP-коллекции» и сохраните. 1. В AI-ассистенте выберите агента и провайдера, затем попросите показать доступные ресурсы каталога. @@ -23,9 +23,9 @@ description: Подготовка платформенного агента ddp- ## Изменение инструментов и навыков -Для расширения возможностей отредактируйте коллекцию или подключите другую. Например, для процессов добавьте `get_processes`, `run_process` и `get_process_instance`. Пользователю также необходимы доступ к этим инструментам через коллекции и разрешения на операции с сущностями. +Для расширения возможностей отредактируйте коллекцию или подключите другую. Например, для процессов добавьте `curated_get_processes`, `curated_run_process` и `curated_get_process_instance`. Пользователю также необходимы доступ к этим инструментам через коллекции и разрешения на операции с сущностями. -На вкладке «Инструменты и навыки» можно назначить [навыки](skills/). Для их чтения в запуске должен быть доступен `get_skill`. +На вкладке «Инструменты и навыки» можно назначить [навыки](skills/). Для их чтения в запуске должен быть доступен `curated_get_skill`. При добавлении группы портала целиком новые инструменты этой группы автоматически входят в коллекцию. Если состав должен быть фиксированным, выбирайте отдельные инструменты. diff --git a/content/documentation/admin/ai-agents/skills.ru.md b/content/documentation/admin/ai-agents/skills.ru.md index ea136da..55fbd96 100644 --- a/content/documentation/admin/ai-agents/skills.ru.md +++ b/content/documentation/admin/ai-agents/skills.ru.md @@ -59,11 +59,13 @@ project-check/ 1. Откройте агент в «AI» → «Агенты» → «Каталог» и выберите редактирование. 1. На вкладке «Инструменты и навыки» добавьте навык и выберите конкретную версию либо «Последняя». -1. В «MCP-коллекции» подключите коллекцию с инструментом `get_skill`; для чтения дополнительных файлов добавьте также `get_skill_file`. +1. В «MCP-коллекции» подключите коллекцию с инструментом `curated_get_skill`; для чтения дополнительных файлов добавьте также `curated_get_skill_file`. 1. Предоставьте запускающему пользователю доступ к этим инструментам через доступные ему MCP-коллекции. 1. Сохраните агента и начните новый запуск. -При запуске агент получает названия и описания назначенных навыков и загружает полный текст при необходимости. Без доступного `get_skill` набор навыков не передаётся; форма привязок показывает предупреждение. `list_skills` предназначен для обычного MCP-клиента; агент получает свой подготовленный набор. +При запуске агент получает названия и описания назначенных навыков и загружает полный текст при необходимости. Без доступного `curated_get_skill` набор навыков не передаётся; форма привязок показывает предупреждение. `curated_list_skills` предназначен для обычного MCP-клиента; агент получает свой подготовленный набор. + +Если в `SKILL.md` указаны имена MCP-инструментов для платформенного агента, используйте их с префиксом `ddp_`, например `ddp_curated_get_skill_file` или `ddp_query_catalog`. В каталоге коллекций те же инструменты называются `curated_get_skill_file` и `query_catalog`. Привязка «Последняя» выбирает активную версию с наибольшим номером при следующем запуске. Закреплённая привязка сохраняет выбранную версию. diff --git a/content/documentation/admin/security/rbac.ru.md b/content/documentation/admin/security/rbac.ru.md index 9132262..345693e 100644 --- a/content/documentation/admin/security/rbac.ru.md +++ b/content/documentation/admin/security/rbac.ru.md @@ -295,7 +295,7 @@ AI-агенты и навыки: Для навыка используются `read:agent-skill`, `edit:agent-skill` и `edit:role-bindings`. Для источника навыков — `read:agent-skill-source`, `edit:agent-skill-source` и `edit:role-bindings`. -Назначенный агенту навык не выдаёт дополнительных разрешений. Чтение навыка в запуске требует инструмента `get_skill`, доступного через MCP-коллекции агента и запускающего пользователя. +Назначенный агенту навык не выдаёт дополнительных разрешений. Чтение навыка в запуске требует инструмента `curated_get_skill`, доступного через MCP-коллекции агента и запускающего пользователя. #### Рабочие пространства и шаблоны @@ -311,6 +311,8 @@ AI-агенты и навыки: Прикрепление к чату и выполнение заданий процесса требуют пространства самого пользователя. Для процесса также необходима привязка к его сущности. +Публиковать порты, менять их уровень доступа и отменять публикацию может владелец с правом обновления рабочего пространства. Для приложений «Только владелец» действует такое же ограничение на открытие. Приложения «Пользователи DDP» доступны любому вошедшему незаблокированному пользователю, «Публично» — без входа; права на карточку рабочего пространства для открытия этих ссылок не требуются. Допустимый уровень публикации портов [ограничивается шаблоном](../../workspaces/apps/#уровни-доступа). + Для других объектов (действия, автоматизации, процессы, вебхуки, виджеты, дашборды, внешние сервисы и т. д.): - `read:[object-type]` — просмотр объекта. - `update:[object-type]` — редактирование объекта. diff --git a/content/documentation/admin/widgets/ai/chat.ru.md b/content/documentation/admin/widgets/ai/chat.ru.md index ddfa0aa..51816b9 100644 --- a/content/documentation/admin/widgets/ai/chat.ru.md +++ b/content/documentation/admin/widgets/ai/chat.ru.md @@ -23,12 +23,12 @@ weight: 10 При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должен вызвать агент при подготовке ответа. Агент получает инструменты назначенных ему MCP-коллекций, которыми может пользоваться запускающий пользователь. Без коллекций агент работает без MCP-инструментов. -Чтобы использовать `get_external_data` в промпте, включите его в [MCP-коллекции агента](../../ai-agents/platform-agent/#изменение-инструментов-и-навыков) и предоставьте пользователю доступ к этому инструменту через коллекцию. +Чтобы платформенный агент вызывал `ddp_curated_get_external_data` по инструкции в промпте, включите `curated_get_external_data` в [MCP-коллекции агента](../../ai-agents/platform-agent/#изменение-инструментов-и-навыков) и предоставьте пользователю доступ к этому инструменту через коллекцию. Пример промпта для быстрого вопроса: ```text -1. Вызови MCP tool get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. +1. Вызови MCP-инструмент ddp_curated_get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. 2. Выведи таблицу с последними 10 пайплайнами. ``` diff --git a/content/documentation/admin/workspaces/apps.ru.md b/content/documentation/admin/workspaces/apps.ru.md new file mode 100644 index 0000000..2d4ee48 --- /dev/null +++ b/content/documentation/admin/workspaces/apps.ru.md @@ -0,0 +1,108 @@ +--- +title: Приложения и публикация портов +description: Приложения шаблона рабочего пространства, веб-терминал, резервирование адресов и уровни доступа к опубликованным портам. +weight: 50 +--- + +Шаблон рабочего пространства может публиковать веб-приложения на отдельных HTTPS-адресах и резервировать адреса для портов, которые владелец откроет из портала. Например, шаблон может предоставлять веб-терминал, а пользователь — временно публиковать сервер разрабатываемого приложения. + +Публикация настраивает адрес и доступ. Само приложение запускается контейнером шаблона, скриптом или пользователем. Шлюз `gate` передаёт HTTP-запросы и WebSocket-соединения на порт приложения по `127.0.0.1` внутри пода. + +## Домены и сеть + +Настройте [DNS, Ingress и TLS](network-storage/#публикация-ide) до публикации шаблона. Для адреса IDE `https://ddp-ws-0a26ad26.example-workspaces.com` используются такие адреса: + +| Назначение | Адрес | +| --- | --- | +| Приложение с идентификатором `terminal` | `https://terminal-ddp-ws-0a26ad26.example-workspaces.com` | +| Первый опубликованный порт | `https://p1-ddp-ws-0a26ad26.example-workspaces.com` | + +Wildcard-запись и сертификат для `*.example-workspaces.com` покрывают IDE, приложения и зарезервированные адреса портов. Стартовый Ingress направляет все эти хосты через `gate`. При изменении Ingress сохраните маршруты и TLS для каждого хоста. + +Домен рабочих пространств должен быть отдельным от родительского домена DDP и Dex, для которого браузер допускает cookie. Например, используйте `example-workspaces.com` при адресе портала `ddp.example.com`. Приложение на `ide.example.com` может установить cookie для `example.com`, поэтому такой вариант не обеспечивает разделение с порталом. + +## Приложения шаблона + +В стартовом `main.tf` список `local.apps` содержит веб-терминал. Для добавления приложения измените этот список, например: + +```hcl +apps = [ + { slug = "terminal", name = "Терминал", port = local.terminal_port, share = "owner" }, + { slug = "preview", name = "Предпросмотр", port = 3000, share = "authenticated" }, +] +``` + +Приложение предпросмотра должно самостоятельно запуститься на порту `3000` в поде. Если сервер проверяет заголовок `Host`, разрешите его внешний хост, например `preview-ddp-ws-0a26ad26.example-workspaces.com`. Для сервера разработки Vite это задаётся через `server.allowedHosts`. + +Поля приложения задают адрес, подпись и доступ: + +| Поле | Требования | +| --- | --- | +| `slug` | Уникальный идентификатор до 32 символов: строчные латинские буквы, цифры и дефис; начало и конец — буква или цифра. `ide` и `p` зарезервированы | +| `name` | Название от 1 до 60 символов | +| `port` | Порт приложения от `1` до `65535` | +| `share` | `owner`, `authenticated` или `public` | +| `icon` | Необязательный HTTPS URL иконки | + +В `outputs.tf` обязателен результат: + +```hcl +output "ddp_apps" { + value = local.apps +} +``` + +Если приложений нет, верните пустой список `[]`. Отсутствующий или некорректный `ddp_apps` завершает операцию применения ошибкой. + +## Уровни доступа + +Уровень задаётся отдельно для каждого приложения и опубликованного порта: + +| Значение шаблона | Название в интерфейсе | Кто открывает | +| --- | --- | --- | +| `owner` | «Только владелец» | Владелец с правом обновлять рабочее пространство, как при открытии IDE | +| `authenticated` | «Пользователи DDP» | Любой вошедший в DDP пользователь, который не заблокирован | +| `public` | «Публично» | Любой посетитель без входа в DDP | + +Для `authenticated` не требуется доступ к карточке рабочего пространства. Пользователь открывает переданную ему ссылку и при необходимости входит в портал. Сессии приложений отделены от сессии IDE. + +В настройках шаблона в блоке «Приложения» задайте «Потолок уровня для публикации портов». Владелец не сможет выбрать уровень выше этого значения. Ограничение относится к портам, публикуемым из интерфейса; уровни приложений в `local.apps` задаёт автор шаблона. + +Веб-терминал и другие приложения с выполнением команд от имени владельца оставляйте с `share = "owner"`. Они получают доступ к файлам и токенам внутри пода. + +## Адреса для публикации портов + +Стартовый шаблон резервирует восемь адресов `p1`–`p8`. Чтобы изменить количество, замените значение в существующем блоке `locals`: + +```hcl +app_slots = 8 +``` + +Допустимо от `0` до `100`; значение `0` отключает публикацию портов из интерфейса. Стартовый проект формирует хосты и правила Ingress на основе этого значения. Результат `ddp_runtime` должен возвращать `app_slots` и порт шлюза `gate_port`: + +```hcl +app_slots = local.app_slots +gate_port = local.gate_port +``` + +Добавьте эти поля в существующий объект `value` результата `ddp_runtime`, а не отдельным `output`. + +Публикация из интерфейса занимает свободный адрес без применения OpenTofu. Освобождение адреса выполняется кнопкой «Отменить публикацию». Если новая версия шаблона уменьшает количество адресов, публикации за пределами нового диапазона перестают открываться и помечаются «Адрес не зарезервирован текущей версией шаблона». Владелец может отменить их и при необходимости опубликовать порт заново в доступный адрес. + +## Веб-терминал стартового шаблона + +Стартовый шаблон запускает `ttyd` из штатного образа IDE в контейнере `terminal` и публикует его как приложение «Терминал» с доступом только владельцу. Терминал использует тот же постоянный том, что IDE и агент. Команды выполняются в контейнере терминала с его собственными ограничениями ресурсов. + +Чтобы изменить ограничения, замените значения `terminal_requests` и `terminal_limits` в `main.tf`. Инструменты, установленные [на постоянный том](tools/), доступны и терминалу, если их пути включены в его окружение. + +## Проверка шаблона + +После изменения проверьте черновик в новом рабочем пространстве: + +1. Дождитесь успешной операции создания и откройте вкладку «Приложения». +1. Откройте «Терминал» и проверьте доступ к рабочей директории. +1. Запустите HTTP-приложение на свободном порту и [опубликуйте его из портала](../../user/workspaces/#публикация-порта). +1. Проверьте адрес, TLS и разрешённый уровень доступа. Для `authenticated` проверьте вход другим пользователем; для `public` — открытие без сессии портала. +1. Отмените публикацию и убедитесь, что приложение больше не открывается по этому адресу. + +После проверки опубликуйте и активируйте версию. Существующие рабочие пространства используют прежний состав приложений до [обновления шаблона](../../user/workspaces/#обновление-шаблона). diff --git a/content/documentation/admin/workspaces/network-storage.ru.md b/content/documentation/admin/workspaces/network-storage.ru.md index 197acd0..8679c0a 100644 --- a/content/documentation/admin/workspaces/network-storage.ru.md +++ b/content/documentation/admin/workspaces/network-storage.ru.md @@ -39,12 +39,14 @@ Secret `operations-registry` должен существовать в `d8-develo ## Публикация IDE -IDE каждого рабочего пространства публикуется на собственном HTTPS-хосте. Для домена `ide.example.com` стартовый шаблон создаёт адрес вида `https://ddp-ws-<суффикс>.ide.example.com`. +IDE каждого рабочего пространства публикуется на собственном HTTPS-хосте. Приложения и опубликованные порты получают соседние хосты, например `terminal-ddp-ws-<суффикс>.example-workspaces.com` и `p1-ddp-ws-<суффикс>.example-workspaces.com`. Для домена `example-workspaces.com` стартовый шаблон создаёт адрес вида `https://ddp-ws-<суффикс>.example-workspaces.com`. -Перед запуском подготовьте wildcard-запись `*.ide.example.com`, которая указывает на ingress-контроллер целевого кластера. В `main.tf` задайте: +Домен рабочих пространств должен быть отдельным от родительского домена DDP и Dex, для которого браузер допускает cookie. Например, при портале `ddp.example.com` используйте `example-workspaces.com`; адреса под `ide.example.com` этого разделения не обеспечивают. + +Перед запуском подготовьте wildcard-запись `*.example-workspaces.com`, которая указывает на ingress-контроллер целевого кластера. В `main.tf` задайте: ```hcl -ide_domain = "ide.example.com" +ide_domain = "example-workspaces.com" ingress_class = "nginx" ide_tls_secret = "workspace-ide-tls" ingress_annotations = { @@ -53,7 +55,9 @@ ingress_annotations = { } ``` -Замените `nginx` на существующий IngressClass. Значение `null` выбирает класс по умолчанию. Secret `workspace-ide-tls` должен находиться в неймспейсе шаблона и содержать сертификат для `*.ide.example.com` с доверенной браузером цепочкой. +Замените `nginx` на существующий IngressClass. Значение `null` выбирает класс по умолчанию. Secret `workspace-ide-tls` должен находиться в неймспейсе шаблона и содержать сертификат для `*.example-workspaces.com` с доверенной браузером цепочкой. + +Wildcard-сертификат покрывает IDE, приложения и адреса портов. При изменении правил Ingress сохраните все хосты из `local.app_hosts` и `local.slot_hosts`, их TLS и маршрут через шлюз. Схема адресов описана [в настройке приложений](apps/). Аннотации в примере предназначены для ingress-nginx и увеличивают тайм-ауты длительных соединений IDE. Для другого контроллера задайте поддерживаемые им аннотации. @@ -63,10 +67,10 @@ ingress_annotations = { ## Выдача сертификата через cert-manager -При установленном cert-manager и настроенном ClusterIssuer можно получать отдельный сертификат для каждого пространства. Замените значения в `main.tf`: +При установленном cert-manager и настроенном ClusterIssuer можно получать сертификат для каждого пространства, включающий хост IDE, хосты приложений и все зарезервированные адреса портов. Замените значения в `main.tf`: ```hcl -ide_domain = "ide.example.com" +ide_domain = "example-workspaces.com" ingress_class = "nginx" ide_tls_secret = "${local.name}-ide-tls" ingress_annotations = { diff --git a/content/documentation/admin/workspaces/overview.ru.md b/content/documentation/admin/workspaces/overview.ru.md index 2c186eb..de6c98c 100644 --- a/content/documentation/admin/workspaces/overview.ru.md +++ b/content/documentation/admin/workspaces/overview.ru.md @@ -13,7 +13,7 @@ weight: 10 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. Подготовьте отдельный домен IDE и приложений, wildcard-запись DNS и TLS. Используйте домен, отдельный от родительского домена DDP и Dex, для которого браузер допускает cookie. Адреса должны быть доступны из браузера пользователя. Порядок настройки — [в примерах Ingress и TLS](network-storage/#публикация-ide). 1. Обеспечьте доступ из целевых подов и Jobs операций к HTTPS-адресу портала с доверенным сертификатом. Он используется для состояния OpenTofu, обращения к модели, MCP и проверки доступа в IDE. 1. Если используются закрытые хранилища образов, подготовьте Secrets для скачивания образов [в соответствующих неймспейсах](network-storage/#образы-из-закрытого-хранилища). 1. Для шаблона с репозиторием создайте подключение Git и заполните реквизиты. Пользователям потребуется [AI-провайдер](../../user/ai-assistant/#подключение-ai-провайдера). diff --git a/content/documentation/admin/workspaces/sources.ru.md b/content/documentation/admin/workspaces/sources.ru.md index c591694..45f524f 100644 --- a/content/documentation/admin/workspaces/sources.ru.md +++ b/content/documentation/admin/workspaces/sources.ru.md @@ -30,7 +30,7 @@ workspace-templates/ AGENTS.md ``` -Идентификаторы шаблонов в примере — `go-development` и `project-review`. Непосредственная поддиректория должна содержать файл `.tf` в своём корне; вложенные `files/` и `scripts/` входят в тот же шаблон. Каждый проект должен возвращать [обязательный результат `ddp_runtime`](templates/#связь-с-порталом). +Идентификаторы шаблонов в примере — `go-development` и `project-review`. Непосредственная поддиректория должна содержать файл `.tf` в своём корне; вложенные `files/` и `scripts/` входят в тот же шаблон. Каждый проект должен возвращать [обязательные результаты `ddp_runtime` и `ddp_apps`](templates/#связь-с-порталом). Чтобы перенести ручной шаблон, разместите в GitLab его пользовательские файлы с теми же относительными путями. Не добавляйте создаваемые порталом `ddp.tf`, `ddp.auto.tfvars.json`, состояние OpenTofu и `.terraform`. @@ -74,7 +74,7 @@ workspace-templates/ | «Восстановлен» | Директория вернулась после архивирования источником | | «Пропущен» | Директория не обработана; проверьте указанную причину | -При конфликте идентификатора с ручным шаблоном или шаблоном другого источника существующий объект не перезаписывается. При ошибке проверьте права на GitLab, проект, ветку, путь, допустимость файлов и `ddp_runtime`, затем повторите синхронизацию. +При конфликте идентификатора с ручным шаблоном или шаблоном другого источника существующий объект не перезаписывается. При ошибке проверьте права на GitLab, проект, ветку, путь, допустимость файлов и результаты `ddp_runtime` и `ddp_apps`, затем повторите синхронизацию. ## Удаление директории или источника diff --git a/content/documentation/admin/workspaces/templates.ru.md b/content/documentation/admin/workspaces/templates.ru.md index a93790f..c853389 100644 --- a/content/documentation/admin/workspaces/templates.ru.md +++ b/content/documentation/admin/workspaces/templates.ru.md @@ -4,7 +4,7 @@ description: Создание и изменение шаблона рабоче weight: 20 --- -Шаблон рабочего пространства — проект OpenTofu с подключением Kubernetes, настройками Git и набором навыков. Новый ручной шаблон содержит стартовый проект с контейнерами агента, IDE и проверки доступа, постоянным томом, Service и Ingress. +Шаблон рабочего пространства — проект OpenTofu с подключением Kubernetes, настройками Git и набором навыков. Новый ручной шаблон содержит стартовый проект с контейнерами агента, IDE, веб-терминала и проверки доступа, постоянным томом, Service и Ingress. ## Первый шаблон @@ -15,7 +15,8 @@ weight: 20 1. На вкладке «Подключение» выберите «Подключение Kubernetes» и «Namespace». При необходимости выберите сервисную учётную запись. 1. Для работы с проектом включите «Инициализировать репозиторием», выберите «Подключение Git», задайте HTTPS URL и ветку. Если проект выбирает пользователь, включите «Разрешить переопределять при создании». Для пространства без Git оставьте инициализацию выключенной. 1. Сохраните шаблон и откройте вкладку «Файлы». -1. В `main.tf` задайте `local.ide_domain`, например `ide.example.com`, и проверьте [параметры Ingress, TLS, образов и хранения](network-storage/). +1. В `main.tf` задайте `local.ide_domain`, например `example-workspaces.com`, и проверьте [параметры Ingress, TLS, образов и хранения](network-storage/). Используйте отдельный домен от DDP и Dex. +1. В настройках шаблона в блоке «Приложения» задайте «Потолок уровня для публикации портов». Состав приложений и количество адресов настраиваются [в файлах шаблона](apps/). 1. Нажмите «Сохранить», затем «Опубликовать v1». 1. На вкладке «Версии» нажмите «Активировать v1». @@ -30,7 +31,7 @@ weight: 20 | `versions.tf` | Версия OpenTofu, версия и конфигурация провайдера Kubernetes | | `main.tf` | StatefulSet, постоянный том, Secrets, ConfigMap, Service, Ingress и настройки доставки файлов | | `variables.tf` | Пользовательские параметры формы создания | -| `outputs.tf` | Обязательный результат `ddp_runtime` | +| `outputs.tf` | Обязательные результаты `ddp_runtime` и `ddp_apps` | | `files/` | Текстовые файлы для рабочей директории пространства | | `scripts/create.sh` | Необязательная первоначальная настройка нового тома | | `scripts/start.sh` | Необязательная настройка при каждом запуске | @@ -91,7 +92,7 @@ image_pull_secrets = var.registry_secrets ## Связь с порталом -В шаблоне обязателен `output "ddp_runtime"`. Стартовый проект возвращает: +В шаблоне обязательны `output "ddp_runtime"` и `output "ddp_apps"`. Стартовый проект возвращает: ```hcl output "ddp_runtime" { @@ -103,11 +104,19 @@ output "ddp_runtime" { ide_container = "ide" ide_url = local.ide_url work_directory = local.work_directory + app_slots = local.app_slots + gate_port = local.gate_port } } + +output "ddp_apps" { + value = local.apps +} ``` -Портал использует StatefulSet для запуска и остановки, контейнер агента и его порт для заданий, адрес `ide_url` для открытия IDE. Сохраняйте соответствие результата фактически созданным объектам и HTTPS-адресу IDE при изменении шаблона. +Портал использует StatefulSet для запуска и остановки, контейнер агента и его порт для заданий, адрес `ide_url` для открытия IDE. Поля `app_slots` и `gate_port` обязательны; `app_slots = 0` отключает публикацию портов. Результат `ddp_apps` содержит приложения шаблона или пустой список `[]`. + +Сохраняйте соответствие результатов фактически созданным объектам и HTTPS-адресам при изменении шаблона. Для собственных шаблонов добавьте новые поля, результат `ddp_apps` и [маршруты приложений](apps/); отсутствие обязательного результата или поля завершает операцию ошибкой. ## Навыки и архивирование @@ -128,4 +137,4 @@ output "ddp_runtime" { | Содержимое | Текст в UTF-8 | | Путь | Относительный, без пустых сегментов, `.` и `..` | -Практические примеры — [доставка файлов и скрипты](files/), [установка Go и других инструментов](tools/), [образы, Ingress и хранение](network-storage/), [синхронизация из GitLab](sources/). +Практические примеры — [доставка файлов и скрипты](files/), [установка Go и других инструментов](tools/), [образы, Ingress и хранение](network-storage/), [приложения и порты](apps/), [синхронизация из GitLab](sources/). diff --git a/content/documentation/release-notes/v1.8.0.ru.md b/content/documentation/release-notes/v1.8.0.ru.md index 3b5b898..e7f4235 100644 --- a/content/documentation/release-notes/v1.8.0.ru.md +++ b/content/documentation/release-notes/v1.8.0.ru.md @@ -1,7 +1,7 @@ --- title: v1.8.0 weight: 880 -description: Рабочие пространства с IDE и AI-агентом, каталог навыков, MCP-коллекции для агентов и статистика использования AI. +description: Рабочие пространства с IDE, AI-агентом и приложениями, новые MCP-инструменты, каталог навыков и статистика AI. --- {{< alert level="info" >}} @@ -14,7 +14,6 @@ description: Рабочие пространства с IDE и AI-агентом - Для использования 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. ## Новые возможности @@ -24,14 +23,12 @@ description: Рабочие пространства с IDE и 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-server/) предоставляет инструменты операций API и новые [инструменты работы с каталогом](../user/catalog-explorer/). Коллекция может включать отдельные инструменты, серверы и группы портала целиком. - [Синхронизация внешних MCP-серверов](../user/mcp-management/#автоматическая-синхронизация) поддерживает расписание и сохраняет последний успешный каталог при ошибке. - [Статистика AI](../user/ai-statistics/) показывает использование агентов, моделей, MCP, навыков и рабочих пространств. ## Улучшения -Изменены пользовательские сценарии каталога и процессов: - - Обновлена [страница сущности](../user/catalog/#страница-сущности); в списке доступны фильтры по статусу и команде. - Для задач, AI-шагов и параллельных шлюзов процессов настраивается [тайм-аут](../admin/processes/overview/#задача). - Лимит [чатов AI-ассистента](../user/ai-assistant/#чаты) увеличен с 20 до 50 на пользователя. diff --git a/content/documentation/user/ai-assistant.ru.md b/content/documentation/user/ai-assistant.ru.md index fa42966..123d855 100644 --- a/content/documentation/user/ai-assistant.ru.md +++ b/content/documentation/user/ai-assistant.ru.md @@ -8,6 +8,8 @@ AI-ассистент — чат, встроенный в Deckhouse Development На вопросы в AI-ассистенте отвечает [AI-агент](../admin/ai-agents/overview/). По умолчанию выбран платформенный агент, который разворачивается вместе с порталом. Агент обращается к языковой модели через AI-провайдера пользователя. +Для вопросов о составе каталога, количестве сущностей, связях и причинах ошибок процессов администратор может подключить агенту [обозреватель каталога](catalog-explorer/). + Для работы с AI-ассистентом требуется доступ хотя бы к одному включённому агенту: глобальное `use:ai-agents` или объектное `use:ai-agent`. Владение даёт права при включённом `owner-is-admin`. ## Подключение AI-провайдера @@ -140,7 +142,7 @@ Authorization: Bearer {{ .token }} Для задач с файлами прикрепите [рабочее пространство](workspaces/) кнопкой «Прикрепить рабочее пространство». В этом режиме отвечает OpenCode пространства; IDE и чат используют одну рабочую копию. Настройки подтверждений и очереди описаны [в руководстве по чату рабочего пространства](workspace-chat/). -Если агенту из каталога доступны `get_workspace_templates`, `create_workspace`, `get_workspace` и `attach_workspace`, можно попросить его подготовить пространство прямо из чата. Например: +Если агенту из каталога доступны `curated_get_workspace_templates`, `curated_create_workspace`, `curated_get_workspace` и `curated_attach_workspace`, можно попросить его подготовить пространство прямо из чата. Например: ```text Создай рабочее пространство из шаблона team-development для https://gitlab.example.com/team/service.git на 8 часов и прикрепи его к этому чату. После запуска добавь тест обработчика /healthz. diff --git a/content/documentation/user/ai-statistics.ru.md b/content/documentation/user/ai-statistics.ru.md index 1910bda..3ca636e 100644 --- a/content/documentation/user/ai-statistics.ru.md +++ b/content/documentation/user/ai-statistics.ru.md @@ -43,7 +43,7 @@ weight: 58 | Токены моделей | Учитываются по отчётам использования, полученным от провайдера. «С отчётом об использовании» показывает число запросов с таким отчётом | | p50 и p95 | Приближённые значения длительности по группам измерений; незавершённые операции в них не входят | | Навык «Подключён» | Был назначен агенту или рабочему пространству; это не означает, что агент его прочитал | -| Навык «Использован» | Агент прочитал навык через `get_skill` либо инструмент навыков рабочего пространства | +| Навык «Использован» | Агент прочитал навык через `curated_get_skill` либо инструмент навыков рабочего пространства | | Навык «нет в каталоге» | Навык удалён или прочитан не из каталога DDP | | Рабочие пространства у навыка | Сумма по дням пространств с заданиями; одно пространство может учитываться в разные дни | | «По TTL» | Остановка рабочего пространства по истечении срока работы | diff --git a/content/documentation/user/catalog-explorer.ru.md b/content/documentation/user/catalog-explorer.ru.md new file mode 100644 index 0000000..f67638f --- /dev/null +++ b/content/documentation/user/catalog-explorer.ru.md @@ -0,0 +1,135 @@ +--- +title: Обозреватель каталога +description: Поиск, подсчёт и группировка сущностей через MCP, анализ связей, диагностика процессов и проверка готовности запуска. +--- + +Обозреватель каталога — набор [MCP-инструментов](mcp-server/) для вопросов о сущностях, связях и запусках процессов. Он использует данные каталога портала и не обращается к внешним системам для их обновления. Все инструменты обозревателя только читают данные; проверка готовности также не запускает процесс. + +## Настройка доступа + +Для использования в AI-ассистенте настройте коллекцию и агента: + +1. Создайте включённую [MCP-коллекцию](mcp-management/#mcp-коллекции). +1. В составе коллекции нажмите «Добавить в коллекцию» и выберите «Группы портала целиком» → «Обозреватель каталога». Для ограниченного набора выберите отдельные инструменты из таблицы ниже. +1. Предоставьте пользователям право использовать коллекцию. +1. На вкладке «Инструменты и навыки» выбранного агента подключите эту коллекцию. +1. Предоставьте пользователям права на нужные ресурсы, сущности, процессы и действия. Доступ к коллекции не заменяет эти права. + +Для внешнего MCP-клиента привязка к агенту не требуется. Рабочее пространство использует коллекции и права владельца. + +Обозреватель возвращает только доступные пользователю данные. Если видна хотя бы одна сущность, он также показывает схему её ресурса, чтобы можно было построить запрос по свойствам. Обход связей не проходит через недоступные сущности. Счётчики отражают видимую пользователю часть каталога. + +## Вопросы в AI-ассистенте + +После настройки [откройте AI-ассистента](ai-assistant/#работа-с-ai-ассистентом) и выберите агента с коллекцией. Например, отправьте вопрос: + +```text +Какие сервисы принадлежат моим командам? Сгруппируй их по языку разработки +и покажи количество в каждой группе. Используй свойства из схемы каталога. +``` + +Для анализа связей укажите исходную сущность и направление интересующей зависимости: + +```text +Покажи родителей сущности payments на три уровня вверх. +Для каждой сущности укажи путь связи и состояние проверок. +``` + +Для диагностики процессов задайте период и ожидаемую детализацию: + +```text +Найди неуспешные запуски процессов за вчера для сущностей моих команд. +Покажи шаг и причину ошибки каждого запуска. +``` + +Если название неоднозначно, уточните ресурс или UUID сущности. Ответ зависит от заполненности каталога и записанных событий процесса. Обозреватель не делает вывод о зависании только по длительности запуска. + +## Состав инструментов + +В каталоге коллекций и внешнем MCP-клиенте используются следующие имена. Для модели платформенного агента и OpenCode к ним добавляется `ddp_`, например `ddp_query_catalog`: + +| Инструмент | Назначение | +| --- | --- | +| `describe_me` | Текущий пользователь, команды, роли, разрешения, время и часовой пояс | +| `get_catalog_schema` | Видимые ресурсы, свойства и типы связей; с `resource` — подробности одного ресурса | +| `search_catalog` | Поиск ресурсов, команд и сущностей по словам | +| `query_catalog` | Фильтрация, подсчёт и группировка сущностей | +| `get_entity_summary` | Карточка сущности со свойствами, проверками, связями и последними запусками | +| `get_entity_relation_graph` | Обход связей с глубиной и путём от исходной сущности | +| `list_process_runs` | Поиск, подсчёт и группировка запусков процессов | +| `get_process_run` | Диагностика запуска по событиям текущей попытки: ошибки, подтверждения, повторы и таймеры | +| `find_operations` | Процессы и действия, доступные для чтения и привязанные к ресурсу сущности | +| `check_process_readiness` | Проверка параметров и условий запуска процесса без выполнения | + +Описание и точные аргументы доступны в «AI» → «MCP» → «Каталог» и в `inputSchema` ответа `tools/list`. + +## Примеры вызовов MCP + +Следующие примеры показывают объект `params` для `tools/call`. При передаче тела запроса API используйте аргумент `body`. Сначала вызовите `get_catalog_schema`, чтобы узнать существующие идентификаторы ресурсов, свойств и связей. Идентификаторы `services` и `language` в примере замените на значения своей установки. + +### Сущности моих команд + +Запрос группирует сервисы команд текущего пользователя по языку разработки: + +```json +{ + "name": "query_catalog", + "arguments": { + "body": { + "resource": "services", + "where": {"field": "team", "op": "in", "value": {"context": "myTeams"}}, + "groupBy": "properties.language" + } + } +} +``` + +`{"context":"myTeams"}` подставляет команды вызывающего пользователя. Для фильтра по владельцу используется `{"context":"me"}`. `countOnly: true` возвращает количество сущностей без списка; `groupBy` возвращает группы с их счётчиками. В сгруппированном ответе `total` — число групп, `entities` — число найденных сущностей. + +Для выборки нескольких условий объедините их в `where.and` или `where.or`. Доступны сравнения `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `containsAny`, `isEmpty`, `isNotEmpty` и `between`; набор зависит от типа поля. Обращение к `properties.<идентификатор>` требует параметра `resource`. + +### Неуспешные запуски за вчера + +Запрос выбирает запуски со статусом `Failed` за предыдущий календарный день в часовом поясе Москвы: + +```json +{ + "name": "list_process_runs", + "arguments": { + "body": { + "status": ["Failed"], + "team": {"context": "myTeams"}, + "since": {"calendar": "day", "offset": -1}, + "timezone": "Europe/Moscow", + "limit": 20 + } + } +} +``` + +Для скользящего периода используйте `since: {"last":"24h"}`. `countOnly: true` возвращает количество запусков; `groupBy` группирует их по `status`, `process`, `initiator`, `entity` или `day`. Эти два режима не совмещаются. Для диагностики передайте UUID найденного запуска в `get_process_run` как `run_uuid`. + +В чате портал передаёт часовой пояс браузера. Внешний MCP-клиент задаёт `timezone` явно; без него используется UTC. Неизвестный часовой пояс отклоняет запрос. + +### Проверка перед запуском процесса + +Перед выполнением используйте последовательность: + +1. Найдите сущность через `search_catalog` и получите доступные операции через `find_operations`. +1. Передайте UUID ресурса, сущности и процесса в `check_process_readiness`. В `body` укажите значения запуска: `selectedProperties`, `actions`, `context`, `skippedElementUuids` и `agentProviderRefs`, когда они нужны. +1. Проверьте `ready`, `blockers` и `approvalRequired`. Проверка возвращает первое препятствие; исправьте его по подсказке и повторите вызов. Значения по умолчанию здесь не подставляются. +1. Для выполнения отдельно вызовите операцию API `run_process` либо специализированный `curated_run_process` с его собственной схемой аргументов. + +Проверка требует `control:processes` глобально, на ресурс или сущность. Читаемая операция не обязательно доступна для запуска. Между проверкой и запуском состояние может измениться, поэтому итоговый результат проверяется по ответу запуска. + +## Ограничения и неполные ответы + +При работе со списками учитывайте размер ответа и ограничения запроса: + +- `limit` по умолчанию равен `20`, максимум — `500`. Если `hasMore: true`, продолжайте с `offset`, увеличенным на `returned`. При ограничении размера ответа строк может быть меньше, чем запрошено. +- Для графа связей `depth` задаётся от `1` до `5`. При `truncated: true` следуйте `hints`: уточните тип связи, глубину или лимит. Граф не поддерживает `offset`. +- Дерево `where` допускает до четырёх уровней вложенности и 20 условий. Если запрос слишком сложен, сузьте выборку или глубину обхода связей. +- Карточка `get_entity_summary` сокращает длинные описания и значения. Для полного поля используйте `query_catalog` с `fields` и фильтром по UUID. +- Диагностика запуска отмечает недостающие факты в `unknown`. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки. + +При отказе инструмент возвращает `isError: true` с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос. diff --git a/content/documentation/user/mcp-management.ru.md b/content/documentation/user/mcp-management.ru.md index e22cee7..6dc34f0 100644 --- a/content/documentation/user/mcp-management.ru.md +++ b/content/documentation/user/mcp-management.ru.md @@ -107,7 +107,7 @@ MCP-коллекция объединяет инструменты и опред 1. Откройте «AI» → «MCP» → «MCP-коллекции» и нажмите «Создать коллекцию». 1. Заполните название, идентификатор, описание, владельца и команду. 1. Включите коллекцию переключателем «Включить». -1. В составе коллекции нажмите «Добавить в коллекцию» и выберите отдельные инструменты `ddp_get_resources` и `ddp_get_resource_entities`. +1. В составе коллекции нажмите «Добавить в коллекцию» и выберите отдельные инструменты `get_resources` и `get_resource_entities`. 1. Нажмите «Сохранить». 1. В меню коллекции выберите «Настроить доступ» и выдайте пользователям или командам роль с `use:mcp-collections`. @@ -115,7 +115,9 @@ MCP-коллекция объединяет инструменты и опред ### Группы и серверы целиком -В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», или «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. +В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», «Обозреватель каталога» или «Курируемые», либо «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. + +«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Настройка и примеры — [в руководстве по обозревателю](catalog-explorer/). «Курируемые» объединяет специализированные инструменты с префиксом `curated_`, включая запуск процессов, чтение навыков и подготовку рабочих пространств. Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией. @@ -149,4 +151,4 @@ MCP-коллекция объединяет инструменты и опред При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам. -Часть прежних встроенных инструментов заменена [операциями с префиксом `ddp_`](mcp-server/#инструменты-операций-api). Обновите состав коллекций, сохранённые запросы MCP-клиентов и инструкции навыков. Для навыков агента проверьте доступность `get_skill`. +Имена операций API в MCP-клиенте и каталоге коллекций совпадают с `operationId`, например `get_resources`. Специализированные инструменты используют префикс `curated_`, например `curated_get_skill`. Платформенный агент и OpenCode показывают модели эти имена с дополнительным префиксом `ddp_`. Обновите состав коллекций, сохранённые вызовы и инструкции навыков по [схеме имён инструментов](mcp-server/#имена-инструментов). Для навыков агента проверьте доступность `curated_get_skill` в коллекции. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 68a3ec5..06b2319 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -18,26 +18,37 @@ MCP — это открытый протокол для взаимодейств ## Доступные инструменты -Инструменты портала включают операции API с префиксом `ddp_` и специализированные инструменты, перечисленные ниже. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. +Инструменты портала включают операции API и специализированные инструменты с префиксом `curated_`. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. + +### Имена инструментов + +В MCP-клиенте используйте имя из `tools/list`. Платформенный агент и OpenCode рабочего пространства показывают модели те же инструменты с дополнительным префиксом `ddp_`. При настройке коллекции выбирайте имя без этого префикса: + +| Назначение | MCP-клиент и каталог коллекций | Имя для модели агента | +| --- | --- | --- | +| Операция API | `get_resources` | `ddp_get_resources` | +| Обозреватель каталога | `query_catalog` | `ddp_query_catalog` | +| Специализированный запуск процесса | `curated_run_process` | `ddp_curated_run_process` | +| Чтение навыка | `curated_get_skill` | `ddp_curated_get_skill` | + +Ниже приведены имена для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте `ddp_`; внешний агент может задавать собственное представление имён для модели. ### Инструменты операций API -Имя инструмента операции имеет вид `ddp_`. В «AI» → «MCP» → «Каталог» доступны описание операции и схема её аргументов. Инструменты объединены в группы, например «Каталог», «Действия», «Процессы и автоматизации» и «Рабочие пространства». +Имя инструмента операции совпадает с `operationId` API. В «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` | +| `ddp_get_resources` | `get_resources` | +| `ddp_get_resource_entities` | `get_resource_entities` | +| `get_processes` | `curated_get_processes` | +| `run_process` | `curated_run_process` | +| `get_skill` | `curated_get_skill` | +| `get_process_instances` | `get_entity_process_history` | -При переносе интеграции обновите имя и прочитайте `inputSchema` из `tools/list`: аргументы соответствуют операции API и могут отличаться от прежнего инструмента. Специализированные `get_processes`, `run_process` и `get_process_instance` сохраняют собственные имена и параметры. +При переносе интеграции обновите имя и прочитайте `inputSchema` из `tools/list`: аргументы соответствуют операции API и могут отличаться от прежнего инструмента. Например, `run_process` — операция API, а `curated_run_process` — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются. Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например: @@ -50,9 +61,13 @@ MCP — это открытый протокол для взаимодейств } ``` -Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Проверяйте `status` и тело ответа, в том числе при отказе в доступе и ошибках проверки входных данных. +Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Неуспешный вызов возвращает MCP-результат с `isError: true`; ошибки «Обозревателя каталога» также поясняют, как исправить запрос. + +### Обозреватель каталога + +Группа «Обозреватель каталога» позволяет искать и подсчитывать сущности, получать схему свойств и граф связей, разбирать запуски процессов и проверять готовность запуска без выполнения. Порядок настройки и примеры запросов — [в руководстве по обозревателю](catalog-explorer/). -### get_external_data +### curated_get_external_data Выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя. @@ -78,7 +93,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_processes +### curated_get_processes Получить список процессов с параметрами запуска. @@ -88,7 +103,7 @@ MCP — это открытый протокол для взаимодейств |---|---|---|---| | `include_step_properties` | булево | Нет | Вернуть также задачи процесса, которые принимают собственные значения параметров действия. По умолчанию выключено | -Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Схема элементов процесса не возвращается. +Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Поле `contextPathsComplete` показывает, учтены ли тела действий при сборе путей; перед подготовкой запуска запросите `include_step_properties: true`. Схема элементов процесса не возвращается. Пример: @@ -98,7 +113,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_service_templates +### curated_get_service_templates Получить шаблоны микросервисов из реестра шаблонов. @@ -118,7 +133,7 @@ MCP — это открытый протокол для взаимодейств --- -### run_process +### curated_run_process Запустить процесс для сущности. @@ -130,7 +145,7 @@ MCP — это открытый протокол для взаимодейств | `entity_uuid` | строка | Да | UUID сущности ресурса, к которому привязан процесс | | `properties` | объект | Да | Параметры запуска процесса: идентификатор параметра → значение. Не переданные параметры получают значения по умолчанию. Если задавать нечего, передайте `{}` | | `context` | объект | Нет | [Контекст запуска](../admin/processes/overview/#контекст-запуска), доступный в шаблонах процесса как `.context` | -| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `get_processes` с `include_step_properties` | +| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `curated_get_processes` с `include_step_properties` | | `skipped_element_uuids` | массив | Нет | UUID элементов «AI-агент» и «Шаблон», которые пропускаются в этом запуске | | `agent_provider_refs` | объект | Нет | AI-провайдеры для элементов «AI-агент»: UUID элемента → название провайдера | @@ -147,7 +162,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_process_instance +### curated_get_process_instance Получить один запуск процесса с хранилищем. @@ -156,7 +171,7 @@ MCP — это открытый протокол для взаимодейств | Название | Тип | Обязательность | Описание | |---|---|---|---| | `entity_uuid` | строка | Да | UUID сущности | -| `instance_uuid` | строка | Да | UUID запуска процесса из `ddp_get_entity_process_history` или из ответа `run_process` | +| `instance_uuid` | строка | Да | UUID запуска процесса из `get_entity_process_history` или из ответа `curated_run_process` | | `wait_seconds` | число | Нет | Сколько секунд ждать завершения запуска, не больше 45. Без параметра ответ возвращается сразу | Возвращает: статус запуска, время, активные элементы и [хранилище процесса](../admin/processes/store/). Для статусов `Failed`, `Timeout` и `Partially Completed` ответ содержит поле `failureReason`: элемент, на котором произошла ошибка, итоговое сообщение и последние строки лога этого элемента. @@ -173,11 +188,11 @@ MCP — это открытый протокол для взаимодейств | Инструмент | Аргументы | Результат | | --- | --- | --- | -| `list_skills` | Необязательная строка `q` | Доступные пользователю навыки с описаниями и последними версиями | -| `get_skill` | Обязательный `name`, необязательный `version` | Текст `SKILL.md`, версия и список файлов | -| `get_skill_file` | Обязательные `name` и `path`, необязательный `version` | Текст дополнительного файла | +| `curated_list_skills` | Необязательная строка `q` | Доступные пользователю навыки с описаниями и последними версиями | +| `curated_get_skill` | Обязательный `name`, необязательный `version` | Текст `SKILL.md`, версия и список файлов | +| `curated_get_skill_file` | Обязательные `name` и `path`, необязательный `version` | Текст дополнительного файла | -В обычном MCP-клиенте версия выбирается меткой; без неё используется последняя активная. В запуске агента доступ ограничен назначенными ему навыками и зафиксированными версиями. Бинарные файлы и файлы больше 1 МиБ через `get_skill_file` не читаются. +В обычном MCP-клиенте версия выбирается меткой; без неё используется последняя активная. В запуске агента доступ ограничен назначенными ему навыками и зафиксированными версиями. Бинарные файлы и файлы больше 1 МиБ через `curated_get_skill_file` не читаются. ### Рабочие пространства @@ -185,14 +200,14 @@ MCP — это открытый протокол для взаимодейств | Инструмент | Аргументы | Результат | | --- | --- | --- | -| `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` | Прикрепление пространства к текущему чату | +| `curated_get_workspace_templates` | Нет | Доступные шаблоны с активной версией, настройками репозитория и параметрами | +| `curated_create_workspace` | Обязательные `template_uuid`, `name`, `ttl_hours`; необязательные `provider`, `repository_url`, `base_ref`, `entity_uuid`, `parameters` | Состояние созданного пространства; операция выполняется асинхронно | +| `curated_get_workspace` | Обязательный `workspace_uuid`, необязательный `wait_seconds` до 45 | Статус, готовность, последняя ошибка и активная операция | +| `curated_attach_workspace` | Обязательный `workspace_uuid` | Прикрепление пространства к текущему чату | `provider` можно не передавать, когда подходящий провайдер уже задан в контексте чата. При вызове вне такого контекста укажите его явно. `parameters` — объект значений переменных шаблона; `ttl_hours` — целое число от 1 до 720. -`attach_workspace` работает только в контексте агента, отвечающего в чате портала. Используйте последовательность: получить шаблоны, создать пространство, дождаться готовности, прикрепить его к чату. +`curated_attach_workspace` работает только в контексте агента, отвечающего в чате портала. Используйте последовательность: получить шаблоны, создать пространство, дождаться готовности, прикрепить его к чату. ## Подключение MCP-сервера @@ -261,7 +276,7 @@ Content-Type: application/json "id": 1, "method": "tools/call", "params": { - "name": "ddp_get_resource_entities", + "name": "get_resource_entities", "arguments": { "resource_uuid": "" } @@ -279,7 +294,7 @@ Content-Type: application/json "content": [ { "type": "text", - "text": "[{\"uuid\":\"...\",\"name\":\"Service 1\",\"properties\":{...}},...]" + "text": "{\"status\":200,\"contentType\":\"application/json; charset=utf-8\",\"encoding\":\"json\",\"body\":{\"response\":[],\"error\":null}}" } ] } @@ -296,7 +311,7 @@ Content-Type: application/json Права доступа: - Инструменты работают с теми же правами, что и пользователь. -- `run_process`, `create_workspace`, `attach_workspace` и изменяющие операции `ddp_*` выполняют действия от имени пользователя. `get_external_data` также может отправить `POST`, `PUT`, `PATCH` или `DELETE` во внешний сервис. +- `curated_run_process`, `curated_create_workspace`, `curated_attach_workspace` и изменяющие операции API выполняют действия от имени пользователя. `curated_get_external_data` также может отправить `POST`, `PUT`, `PATCH` или `DELETE` во внешний сервис. - Если у вас нет доступа к ресурсу, инструмент вернёт ошибку доступа. - Данные фильтруются в соответствии с вашими правами RBAC. diff --git a/content/documentation/user/workspaces.ru.md b/content/documentation/user/workspaces.ru.md index 359f548..46661ae 100644 --- a/content/documentation/user/workspaces.ru.md +++ b/content/documentation/user/workspaces.ru.md @@ -32,6 +32,41 @@ IDE открывается на отдельном HTTPS-домене. Вход В терминале IDE команда `opencode` подключается к тому же агенту, который отвечает в чате портала. Изменения файлов видны в IDE и в чате. Для сохранения результата в Git проверьте изменения, создайте коммит и отправьте его в репозиторий. +## Приложения рабочего пространства + +На вкладке «Приложения» доступны приложения шаблона и опубликованные порты. В стартовом шаблоне приложение «Терминал» открывает командную строку в браузере с доступом к файлам рабочего пространства. Его может открыть только владелец с правом обновления пространства. + +Чтобы открыть приложение, нажмите «Открыть» в его карточке. Индикатор «Работает» означает, что порт слушается в поде; готовность самого приложения проверьте после открытия. После запуска сервера нажмите «Обновить», чтобы перечитать состояние портов. + +### Публикация порта + +Для предпросмотра веб-приложения опубликуйте его порт: + +1. Запустите HTTP-сервер в IDE, веб-терминале или через агента. Он должен быть доступен по `127.0.0.1` внутри пода. Публикация поддерживает HTTP и WebSocket. +1. Откройте вкладку «Приложения» и нажмите «Опубликовать порт». Можно также нажать «Опубликовать» у нужного порта в блоке «Порты, которые слушаются в поде». +1. Заполните «Название», «Порт» и «Уровень доступа». Допустимые уровни ограничены шаблоном. +1. Подтвердите публикацию и откройте полученный адрес. При необходимости скопируйте его кнопкой «Скопировать адрес». + +Публикация доступна владельцу с правом `update:workspaces` или `update:workspace`. Она создаёт маршрут и не запускает приложение. Для сервера с проверкой заголовка `Host` разрешите внешний хост опубликованного порта. + +Адрес имеет вид `https://p1-ddp-ws-<суффикс>.<домен-рабочих-пространств>`. Количество свободных адресов задаёт шаблон; в стартовом шаблоне их восемь. Если свободных адресов нет, отмените ненужную публикацию. Порт, уже занятый приложением шаблона, повторно не публикуется. + +### Доступ по ссылке + +Перед передачей ссылки выберите подходящий «Уровень доступа»: + +| Уровень | Кто может открыть | +| --- | --- | +| «Только владелец» | Владелец с правом обновления рабочего пространства | +| «Пользователи DDP» | Любой вошедший в портал пользователь, который не заблокирован | +| «Публично» | Любой посетитель без входа в портал | + +Доступ по ссылке к приложению не предоставляет доступ к карточке пространства, IDE или чату. Веб-терминалы оставляйте доступными только владельцу: команды получают доступ к его файлам и токенам внутри пода. + +Уровень опубликованного порта меняется в его строке. Чтобы закрыть адрес и освободить место, нажмите «Отменить публикацию» и подтвердите действие. Сервер внутри пода при этом продолжает работать. Изменения маршрутов применяются в течение примерно 15 секунд. + +Остановка рабочего пространства делает приложения недоступными; после запуска опубликованные адреса снова используются. Если после обновления шаблона появился текст «Адрес не зарезервирован текущей версией шаблона», отмените такую публикацию и опубликуйте порт в свободный адрес. + ## Задание агенту в чате Чтобы агент изменил проект: From 76ffd2ddf8401e3800bbbd70393e24f54393f120 Mon Sep 17 00:00:00 2001 From: Nikita Velgin Date: Thu, 29 Oct 2026 12:36:59 +0300 Subject: [PATCH 2/2] ai-docs --- .../admin/ai-agents/external-agents.ru.md | 2 +- .../admin/ai-agents/overview.ru.md | 4 +- .../admin/ai-agents/skills.ru.md | 2 +- .../documentation/release-notes/v1.8.0.ru.md | 2 +- content/documentation/user/ai-assistant.ru.md | 32 ++++- .../documentation/user/catalog-explorer.ru.md | 135 ------------------ .../documentation/user/mcp-management.ru.md | 4 +- content/documentation/user/mcp-server.ru.md | 115 ++++++++++++--- 8 files changed, 129 insertions(+), 167 deletions(-) delete mode 100644 content/documentation/user/catalog-explorer.ru.md diff --git a/content/documentation/admin/ai-agents/external-agents.ru.md b/content/documentation/admin/ai-agents/external-agents.ru.md index 560e340..a9919b9 100644 --- a/content/documentation/admin/ai-agents/external-agents.ru.md +++ b/content/documentation/admin/ai-agents/external-agents.ru.md @@ -107,7 +107,7 @@ curl -s -X POST "https:///api/v2/agent-mcp/tools/call" -H "X-Agent-Run-T Инструмент, которого нет в `ddp.mcp.toolAllowlist`, возвращает ошибку `403`. Недействительный или отозванный токен — ошибку `401`. -Этот эндпоинт принимает имена из списка инструментов без префикса агента: `get_resources`, `query_catalog`, `curated_get_skill`. Префикс `ddp_` платформенный агент добавляет только при передаче инструментов модели. При реализации внешнего агента сохраняйте соответствие между именем для модели и именем, отправляемым порталу. +Этот эндпоинт принимает названия из списка инструментов без префикса агента: `get_resources`, `query_catalog`, `curated_get_skill`. Префикс `ddp_` платформенный агент добавляет только при передаче инструментов модели. При реализации внешнего агента сохраняйте соответствие между названием для модели и названием, отправляемым порталу. ### Обращение к модели через портал diff --git a/content/documentation/admin/ai-agents/overview.ru.md b/content/documentation/admin/ai-agents/overview.ru.md index 2d20d4d..edf8548 100644 --- a/content/documentation/admin/ai-agents/overview.ru.md +++ b/content/documentation/admin/ai-agents/overview.ru.md @@ -46,9 +46,9 @@ AI-агент получает задачу на естественном язы Пошаговая настройка — [в руководстве по MCP-коллекциям](../../user/mcp-management/#mcp-коллекции). -Для поиска, подсчёта и группировки сущностей, анализа связей и диагностики процессов подключите группу «Обозреватель каталога». Настройка и примеры — [в руководстве по обозревателю](../../user/catalog-explorer/). +Для поиска, подсчёта и группировки сущностей, анализа связей и диагностики процессов добавьте группу «Обозреватель каталога» в MCP-коллекцию агента и предоставьте пользователям право использовать коллекцию. Доступ к коллекции не заменяет права на ресурсы, сущности, процессы и действия. Состав инструментов и примеры вызовов — [в справочнике MCP](../../user/mcp-server/#инструменты-работы-с-каталогом). -В коллекциях используются имена `get_resources`, `curated_run_process` и `curated_get_skill`. В инструкциях платформенному агенту добавляйте префикс `ddp_`: `ddp_get_resources`, `ddp_curated_run_process`, `ddp_curated_get_skill`. Полная [схема имён инструментов](../../user/mcp-server/#имена-инструментов) учитывает и вызовы из внешнего MCP-клиента. +В коллекциях используются названия `get_resources`, `curated_run_process` и `curated_get_skill`. В инструкциях платформенному агенту добавляйте префикс `ddp_`: `ddp_get_resources`, `ddp_curated_run_process`, `ddp_curated_get_skill`. Полная [схема названий инструментов](../../user/mcp-server/#названия-инструментов) учитывает и вызовы из внешнего MCP-клиента. ## Навыки агента diff --git a/content/documentation/admin/ai-agents/skills.ru.md b/content/documentation/admin/ai-agents/skills.ru.md index 55fbd96..29faa9e 100644 --- a/content/documentation/admin/ai-agents/skills.ru.md +++ b/content/documentation/admin/ai-agents/skills.ru.md @@ -65,7 +65,7 @@ project-check/ При запуске агент получает названия и описания назначенных навыков и загружает полный текст при необходимости. Без доступного `curated_get_skill` набор навыков не передаётся; форма привязок показывает предупреждение. `curated_list_skills` предназначен для обычного MCP-клиента; агент получает свой подготовленный набор. -Если в `SKILL.md` указаны имена MCP-инструментов для платформенного агента, используйте их с префиксом `ddp_`, например `ddp_curated_get_skill_file` или `ddp_query_catalog`. В каталоге коллекций те же инструменты называются `curated_get_skill_file` и `query_catalog`. +Если инструкция в `SKILL.md` прямо называет MCP-инструмент для платформенного агента, укажите его название с префиксом `ddp_`, например `ddp_curated_get_skill_file` или `ddp_query_catalog`. В каталоге коллекций те же инструменты называются `curated_get_skill_file` и `query_catalog`. Привязка «Последняя» выбирает активную версию с наибольшим номером при следующем запуске. Закреплённая привязка сохраняет выбранную версию. diff --git a/content/documentation/release-notes/v1.8.0.ru.md b/content/documentation/release-notes/v1.8.0.ru.md index e7f4235..86a588d 100644 --- a/content/documentation/release-notes/v1.8.0.ru.md +++ b/content/documentation/release-notes/v1.8.0.ru.md @@ -23,7 +23,7 @@ description: Рабочие пространства с IDE, 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 и новые [инструменты работы с каталогом](../user/catalog-explorer/). Коллекция может включать отдельные инструменты, серверы и группы портала целиком. +- [MCP-сервер](../user/mcp-server/) предоставляет инструменты операций API и новые инструменты работы с каталогом. Коллекция может включать отдельные инструменты, серверы и группы портала целиком. - [Синхронизация внешних MCP-серверов](../user/mcp-management/#автоматическая-синхронизация) поддерживает расписание и сохраняет последний успешный каталог при ошибке. - [Статистика AI](../user/ai-statistics/) показывает использование агентов, моделей, MCP, навыков и рабочих пространств. diff --git a/content/documentation/user/ai-assistant.ru.md b/content/documentation/user/ai-assistant.ru.md index 123d855..1ed6d25 100644 --- a/content/documentation/user/ai-assistant.ru.md +++ b/content/documentation/user/ai-assistant.ru.md @@ -8,8 +8,6 @@ AI-ассистент — чат, встроенный в Deckhouse Development На вопросы в AI-ассистенте отвечает [AI-агент](../admin/ai-agents/overview/). По умолчанию выбран платформенный агент, который разворачивается вместе с порталом. Агент обращается к языковой модели через AI-провайдера пользователя. -Для вопросов о составе каталога, количестве сущностей, связях и причинах ошибок процессов администратор может подключить агенту [обозреватель каталога](catalog-explorer/). - Для работы с AI-ассистентом требуется доступ хотя бы к одному включённому агенту: глобальное `use:ai-agents` или объектное `use:ai-agent`. Владение даёт права при включённом `owner-is-admin`. ## Подключение AI-провайдера @@ -129,14 +127,38 @@ Authorization: Bearer {{ .token }} ### Инструменты MCP -Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Набор задают [MCP-коллекции](mcp-management/#mcp-коллекции) на вкладке «Инструменты и навыки» подключения агента. В запуск попадают инструменты этих коллекций, которыми может пользоваться запускающий пользователь. Это правило распространяется и на платформенного агента; без коллекций агент работает без MCP-инструментов. +Агент вызывает инструменты портала, чтобы получить данные или выполнить действие. Доступные инструменты настраивает администратор. Агент использует их с правами пользователя; если нужный инструмент недоступен, обратитесь к администратору. Кнопка «Инструменты» в окне ассистента открывает список инструментов с типом (`internal`, `external`, `custom`), числом аргументов и примером запроса. Кнопка «В поле ввода» вставляет пример в поле ввода. Вызовы инструментов отображаются в ответе агента со статусом «Вызывается», «Вызван», «Ошибка» или «Отменён», длительностью, аргументами и текстом ошибки. -- Встроенные инструменты (`internal`) и их параметры описаны в [документации MCP-сервера](../mcp-server/). -- Подключение MCP-серверов, пользовательских MCP-инструментов и настройка коллекций — в разделе [«Управление MCP»](../mcp-management/). +Встроенные инструменты (`internal`) и их параметры описаны [в справочнике MCP-сервера](../mcp-server/). + +### Вопросы о каталоге и процессах + +Если администратор предоставил агенту инструменты работы с каталогом, задавайте вопросы о сущностях, связях и запусках процессов. Например: + +```text +Какие сервисы принадлежат моим командам? Сгруппируй их по языку разработки +и покажи количество в каждой группе. Используй свойства из схемы каталога. +``` + +Для анализа связей укажите исходную сущность и направление интересующей зависимости: + +```text +Покажи родителей сущности payments на три уровня вверх. +Для каждой сущности укажи путь связи и состояние проверок. +``` + +Для диагностики процессов задайте период и ожидаемую детализацию: + +```text +Найди неуспешные запуски процессов за вчера для сущностей моих команд. +Покажи шаг и причину ошибки каждого запуска. +``` + +Если название неоднозначно, уточните ресурс или UUID сущности. Ответ зависит от заполненности каталога и записанных событий процесса. Одна лишь длительность запуска не подтверждает, что процесс завис. ## Работа с проектом diff --git a/content/documentation/user/catalog-explorer.ru.md b/content/documentation/user/catalog-explorer.ru.md deleted file mode 100644 index f67638f..0000000 --- a/content/documentation/user/catalog-explorer.ru.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Обозреватель каталога -description: Поиск, подсчёт и группировка сущностей через MCP, анализ связей, диагностика процессов и проверка готовности запуска. ---- - -Обозреватель каталога — набор [MCP-инструментов](mcp-server/) для вопросов о сущностях, связях и запусках процессов. Он использует данные каталога портала и не обращается к внешним системам для их обновления. Все инструменты обозревателя только читают данные; проверка готовности также не запускает процесс. - -## Настройка доступа - -Для использования в AI-ассистенте настройте коллекцию и агента: - -1. Создайте включённую [MCP-коллекцию](mcp-management/#mcp-коллекции). -1. В составе коллекции нажмите «Добавить в коллекцию» и выберите «Группы портала целиком» → «Обозреватель каталога». Для ограниченного набора выберите отдельные инструменты из таблицы ниже. -1. Предоставьте пользователям право использовать коллекцию. -1. На вкладке «Инструменты и навыки» выбранного агента подключите эту коллекцию. -1. Предоставьте пользователям права на нужные ресурсы, сущности, процессы и действия. Доступ к коллекции не заменяет эти права. - -Для внешнего MCP-клиента привязка к агенту не требуется. Рабочее пространство использует коллекции и права владельца. - -Обозреватель возвращает только доступные пользователю данные. Если видна хотя бы одна сущность, он также показывает схему её ресурса, чтобы можно было построить запрос по свойствам. Обход связей не проходит через недоступные сущности. Счётчики отражают видимую пользователю часть каталога. - -## Вопросы в AI-ассистенте - -После настройки [откройте AI-ассистента](ai-assistant/#работа-с-ai-ассистентом) и выберите агента с коллекцией. Например, отправьте вопрос: - -```text -Какие сервисы принадлежат моим командам? Сгруппируй их по языку разработки -и покажи количество в каждой группе. Используй свойства из схемы каталога. -``` - -Для анализа связей укажите исходную сущность и направление интересующей зависимости: - -```text -Покажи родителей сущности payments на три уровня вверх. -Для каждой сущности укажи путь связи и состояние проверок. -``` - -Для диагностики процессов задайте период и ожидаемую детализацию: - -```text -Найди неуспешные запуски процессов за вчера для сущностей моих команд. -Покажи шаг и причину ошибки каждого запуска. -``` - -Если название неоднозначно, уточните ресурс или UUID сущности. Ответ зависит от заполненности каталога и записанных событий процесса. Обозреватель не делает вывод о зависании только по длительности запуска. - -## Состав инструментов - -В каталоге коллекций и внешнем MCP-клиенте используются следующие имена. Для модели платформенного агента и OpenCode к ним добавляется `ddp_`, например `ddp_query_catalog`: - -| Инструмент | Назначение | -| --- | --- | -| `describe_me` | Текущий пользователь, команды, роли, разрешения, время и часовой пояс | -| `get_catalog_schema` | Видимые ресурсы, свойства и типы связей; с `resource` — подробности одного ресурса | -| `search_catalog` | Поиск ресурсов, команд и сущностей по словам | -| `query_catalog` | Фильтрация, подсчёт и группировка сущностей | -| `get_entity_summary` | Карточка сущности со свойствами, проверками, связями и последними запусками | -| `get_entity_relation_graph` | Обход связей с глубиной и путём от исходной сущности | -| `list_process_runs` | Поиск, подсчёт и группировка запусков процессов | -| `get_process_run` | Диагностика запуска по событиям текущей попытки: ошибки, подтверждения, повторы и таймеры | -| `find_operations` | Процессы и действия, доступные для чтения и привязанные к ресурсу сущности | -| `check_process_readiness` | Проверка параметров и условий запуска процесса без выполнения | - -Описание и точные аргументы доступны в «AI» → «MCP» → «Каталог» и в `inputSchema` ответа `tools/list`. - -## Примеры вызовов MCP - -Следующие примеры показывают объект `params` для `tools/call`. При передаче тела запроса API используйте аргумент `body`. Сначала вызовите `get_catalog_schema`, чтобы узнать существующие идентификаторы ресурсов, свойств и связей. Идентификаторы `services` и `language` в примере замените на значения своей установки. - -### Сущности моих команд - -Запрос группирует сервисы команд текущего пользователя по языку разработки: - -```json -{ - "name": "query_catalog", - "arguments": { - "body": { - "resource": "services", - "where": {"field": "team", "op": "in", "value": {"context": "myTeams"}}, - "groupBy": "properties.language" - } - } -} -``` - -`{"context":"myTeams"}` подставляет команды вызывающего пользователя. Для фильтра по владельцу используется `{"context":"me"}`. `countOnly: true` возвращает количество сущностей без списка; `groupBy` возвращает группы с их счётчиками. В сгруппированном ответе `total` — число групп, `entities` — число найденных сущностей. - -Для выборки нескольких условий объедините их в `where.and` или `where.or`. Доступны сравнения `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `containsAny`, `isEmpty`, `isNotEmpty` и `between`; набор зависит от типа поля. Обращение к `properties.<идентификатор>` требует параметра `resource`. - -### Неуспешные запуски за вчера - -Запрос выбирает запуски со статусом `Failed` за предыдущий календарный день в часовом поясе Москвы: - -```json -{ - "name": "list_process_runs", - "arguments": { - "body": { - "status": ["Failed"], - "team": {"context": "myTeams"}, - "since": {"calendar": "day", "offset": -1}, - "timezone": "Europe/Moscow", - "limit": 20 - } - } -} -``` - -Для скользящего периода используйте `since: {"last":"24h"}`. `countOnly: true` возвращает количество запусков; `groupBy` группирует их по `status`, `process`, `initiator`, `entity` или `day`. Эти два режима не совмещаются. Для диагностики передайте UUID найденного запуска в `get_process_run` как `run_uuid`. - -В чате портал передаёт часовой пояс браузера. Внешний MCP-клиент задаёт `timezone` явно; без него используется UTC. Неизвестный часовой пояс отклоняет запрос. - -### Проверка перед запуском процесса - -Перед выполнением используйте последовательность: - -1. Найдите сущность через `search_catalog` и получите доступные операции через `find_operations`. -1. Передайте UUID ресурса, сущности и процесса в `check_process_readiness`. В `body` укажите значения запуска: `selectedProperties`, `actions`, `context`, `skippedElementUuids` и `agentProviderRefs`, когда они нужны. -1. Проверьте `ready`, `blockers` и `approvalRequired`. Проверка возвращает первое препятствие; исправьте его по подсказке и повторите вызов. Значения по умолчанию здесь не подставляются. -1. Для выполнения отдельно вызовите операцию API `run_process` либо специализированный `curated_run_process` с его собственной схемой аргументов. - -Проверка требует `control:processes` глобально, на ресурс или сущность. Читаемая операция не обязательно доступна для запуска. Между проверкой и запуском состояние может измениться, поэтому итоговый результат проверяется по ответу запуска. - -## Ограничения и неполные ответы - -При работе со списками учитывайте размер ответа и ограничения запроса: - -- `limit` по умолчанию равен `20`, максимум — `500`. Если `hasMore: true`, продолжайте с `offset`, увеличенным на `returned`. При ограничении размера ответа строк может быть меньше, чем запрошено. -- Для графа связей `depth` задаётся от `1` до `5`. При `truncated: true` следуйте `hints`: уточните тип связи, глубину или лимит. Граф не поддерживает `offset`. -- Дерево `where` допускает до четырёх уровней вложенности и 20 условий. Если запрос слишком сложен, сузьте выборку или глубину обхода связей. -- Карточка `get_entity_summary` сокращает длинные описания и значения. Для полного поля используйте `query_catalog` с `fields` и фильтром по UUID. -- Диагностика запуска отмечает недостающие факты в `unknown`. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки. - -При отказе инструмент возвращает `isError: true` с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос. diff --git a/content/documentation/user/mcp-management.ru.md b/content/documentation/user/mcp-management.ru.md index 6dc34f0..5bb772e 100644 --- a/content/documentation/user/mcp-management.ru.md +++ b/content/documentation/user/mcp-management.ru.md @@ -117,7 +117,7 @@ MCP-коллекция объединяет инструменты и опред В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», «Обозреватель каталога» или «Курируемые», либо «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. -«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Настройка и примеры — [в руководстве по обозревателю](catalog-explorer/). «Курируемые» объединяет специализированные инструменты с префиксом `curated_`, включая запуск процессов, чтение навыков и подготовку рабочих пространств. +«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Состав инструментов и примеры вызовов — [в справочнике MCP](mcp-server/#инструменты-работы-с-каталогом). «Курируемые» объединяет специализированные инструменты с префиксом `curated_`, включая запуск процессов, чтение навыков и подготовку рабочих пространств. Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией. @@ -150,5 +150,3 @@ MCP-коллекция объединяет инструменты и опред ## Настройка после обновления При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам. - -Имена операций API в MCP-клиенте и каталоге коллекций совпадают с `operationId`, например `get_resources`. Специализированные инструменты используют префикс `curated_`, например `curated_get_skill`. Платформенный агент и OpenCode показывают модели эти имена с дополнительным префиксом `ddp_`. Обновите состав коллекций, сохранённые вызовы и инструкции навыков по [схеме имён инструментов](mcp-server/#имена-инструментов). Для навыков агента проверьте доступность `curated_get_skill` в коллекции. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 06b2319..e4446ed 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -20,35 +20,24 @@ MCP — это открытый протокол для взаимодейств Инструменты портала включают операции API и специализированные инструменты с префиксом `curated_`. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа `external` доступны после [синхронизации каталога MCP-сервера](../mcp-management/#mcp-серверы) и [добавления инструментов в MCP-коллекцию](../mcp-management/#mcp-коллекции). Инструменты типа `custom` [создаются вручную](../mcp-management/#mcp-инструменты) в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию. -### Имена инструментов +### Названия инструментов -В MCP-клиенте используйте имя из `tools/list`. Платформенный агент и OpenCode рабочего пространства показывают модели те же инструменты с дополнительным префиксом `ddp_`. При настройке коллекции выбирайте имя без этого префикса: +В MCP-клиенте используйте название из `tools/list`. Платформенный агент и OpenCode рабочего пространства показывают модели те же инструменты с дополнительным префиксом `ddp_`. При настройке коллекции выбирайте название без этого префикса: -| Назначение | MCP-клиент и каталог коллекций | Имя для модели агента | +| Назначение | MCP-клиент и каталог коллекций | Название для модели агента | | --- | --- | --- | | Операция API | `get_resources` | `ddp_get_resources` | | Обозреватель каталога | `query_catalog` | `ddp_query_catalog` | | Специализированный запуск процесса | `curated_run_process` | `ddp_curated_run_process` | | Чтение навыка | `curated_get_skill` | `ddp_curated_get_skill` | -Ниже приведены имена для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте `ddp_`; внешний агент может задавать собственное представление имён для модели. +Ниже приведены названия для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте `ddp_`; внешний агент может задавать собственное представление названий для модели. ### Инструменты операций API -Имя инструмента операции совпадает с `operationId` API. В «AI» → «MCP» → «Каталог» доступны описание операции и схема её аргументов. Инструменты объединены в группы, например «Каталог», «Обозреватель каталога», «Действия», «Процессы и автоматизации» и «Рабочие пространства». Специализированные инструменты находятся в группе «Курируемые». +В «AI» → «MCP» → «Каталог» отображаются названия инструментов, например `get_resources` и `get_resource_entities`, их описания и соответствующие HTTP-методы и пути API. По нажатию на название инструмента открывается схема его аргументов. Инструменты объединены в группы, например «Каталог», «Обозреватель каталога», «Действия», «Процессы и автоматизации» и «Рабочие пространства». Специализированные инструменты находятся в группе «Курируемые». -Примеры замены прежних имён: - -| Прежнее имя | Актуальный инструмент | -| --- | --- | -| `ddp_get_resources` | `get_resources` | -| `ddp_get_resource_entities` | `get_resource_entities` | -| `get_processes` | `curated_get_processes` | -| `run_process` | `curated_run_process` | -| `get_skill` | `curated_get_skill` | -| `get_process_instances` | `get_entity_process_history` | - -При переносе интеграции обновите имя и прочитайте `inputSchema` из `tools/list`: аргументы соответствуют операции API и могут отличаться от прежнего инструмента. Например, `run_process` — операция API, а `curated_run_process` — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются. +Аргументы инструмента описаны в `inputSchema` ответа `tools/list`. Например, `run_process` — операция API, а `curated_run_process` — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются. Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например: @@ -63,9 +52,97 @@ MCP — это открытый протокол для взаимодейств Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Неуспешный вызов возвращает MCP-результат с `isError: true`; ошибки «Обозревателя каталога» также поясняют, как исправить запрос. -### Обозреватель каталога +### Инструменты работы с каталогом + +Инструменты группы «Обозреватель каталога» ищут и подсчитывают сущности, получают схему свойств и граф связей, разбирают запуски процессов и проверяют готовность запуска. Все эти инструменты только читают данные; проверка готовности не запускает процесс. + +Результаты и счётчики ограничены доступными пользователю данными. Если видна хотя бы одна сущность, инструменты также показывают схему её ресурса для запросов по свойствам. Обход связей не проходит через недоступные сущности. + +В каталоге коллекций и внешнем MCP-клиенте используются следующие названия. Для модели платформенного агента и OpenCode к ним добавляется `ddp_`, например `ddp_query_catalog`: + +| Инструмент | Назначение | +| --- | --- | +| `describe_me` | Текущий пользователь, команды, роли, разрешения, время и часовой пояс | +| `get_catalog_schema` | Видимые ресурсы, свойства и типы связей; с `resource` — подробности одного ресурса | +| `search_catalog` | Поиск ресурсов, команд и сущностей по словам | +| `query_catalog` | Фильтрация, подсчёт и группировка сущностей | +| `get_entity_summary` | Карточка сущности со свойствами, проверками, связями и последними запусками | +| `get_entity_relation_graph` | Обход связей с глубиной и путём от исходной сущности | +| `list_process_runs` | Поиск, подсчёт и группировка запусков процессов | +| `get_process_run` | Диагностика запуска по событиям текущей попытки: ошибки, подтверждения, повторы и таймеры | +| `find_operations` | Процессы и действия, доступные для чтения и привязанные к ресурсу сущности | +| `check_process_readiness` | Проверка параметров и условий запуска процесса без выполнения | + +Описание и точные аргументы доступны в «AI» → «MCP» → «Каталог» и в `inputSchema` ответа `tools/list`. + +Следующие примеры показывают объект `params` для `tools/call`. При передаче тела запроса API используйте аргумент `body`. Сначала вызовите `get_catalog_schema`, чтобы узнать существующие идентификаторы ресурсов, свойств и связей. Идентификаторы `services` и `language` в примере замените на значения своей установки. + +#### Сущности моих команд + +Запрос группирует сервисы команд текущего пользователя по языку разработки: + +```json +{ + "name": "query_catalog", + "arguments": { + "body": { + "resource": "services", + "where": {"field": "team", "op": "in", "value": {"context": "myTeams"}}, + "groupBy": "properties.language" + } + } +} +``` + +`{"context":"myTeams"}` подставляет команды вызывающего пользователя. Для фильтра по владельцу используется `{"context":"me"}`. `countOnly: true` возвращает количество сущностей без списка; `groupBy` возвращает группы с их счётчиками. В сгруппированном ответе `total` — число групп, `entities` — число найденных сущностей. + +Для выборки нескольких условий объедините их в `where.and` или `where.or`. Доступны сравнения `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `containsAny`, `isEmpty`, `isNotEmpty` и `between`; набор зависит от типа поля. Обращение к `properties.<идентификатор>` требует параметра `resource`. + +#### Неуспешные запуски за вчера + +Запрос выбирает запуски со статусом `Failed` за предыдущий календарный день в часовом поясе Москвы: + +```json +{ + "name": "list_process_runs", + "arguments": { + "body": { + "status": ["Failed"], + "team": {"context": "myTeams"}, + "since": {"calendar": "day", "offset": -1}, + "timezone": "Europe/Moscow", + "limit": 20 + } + } +} +``` + +Для скользящего периода используйте `since: {"last":"24h"}`. `countOnly: true` возвращает количество запусков; `groupBy` группирует их по `status`, `process`, `initiator`, `entity` или `day`. Эти два режима не совмещаются. Для диагностики передайте UUID найденного запуска в `get_process_run` как `run_uuid`. + +В чате портал передаёт часовой пояс браузера. Внешний MCP-клиент задаёт `timezone` явно; без него используется UTC. Неизвестный часовой пояс отклоняет запрос. + +#### Проверка перед запуском процесса + +Перед выполнением используйте последовательность: + +1. Найдите сущность через `search_catalog` и получите доступные операции через `find_operations`. +1. Передайте UUID ресурса, сущности и процесса в `check_process_readiness`. В `body` укажите значения запуска: `selectedProperties`, `actions`, `context`, `skippedElementUuids` и `agentProviderRefs`, когда они нужны. +1. Проверьте `ready`, `blockers` и `approvalRequired`. Проверка возвращает первое препятствие; исправьте его по подсказке и повторите вызов. Значения по умолчанию здесь не подставляются. +1. Для выполнения отдельно вызовите операцию API `run_process` либо специализированный `curated_run_process` с его собственной схемой аргументов. + +Проверка требует `control:processes` глобально, на ресурс или сущность. Читаемая операция не обязательно доступна для запуска. Между проверкой и запуском состояние может измениться, поэтому итоговый результат проверяется по ответу запуска. + +#### Ограничения и неполные ответы + +При работе со списками учитывайте размер ответа и ограничения запроса: + +- `limit` по умолчанию равен `20`, максимум — `500`. Если `hasMore: true`, продолжайте с `offset`, увеличенным на `returned`. При ограничении размера ответа строк может быть меньше, чем запрошено. +- Для графа связей `depth` задаётся от `1` до `5`. При `truncated: true` следуйте `hints`: уточните тип связи, глубину или лимит. Граф не поддерживает `offset`. +- Дерево `where` допускает до четырёх уровней вложенности и 20 условий. Если запрос слишком сложен, сузьте выборку или глубину обхода связей. +- Карточка `get_entity_summary` сокращает длинные описания и значения. Для полного поля используйте `query_catalog` с `fields` и фильтром по UUID. +- Диагностика запуска отмечает недостающие факты в `unknown`. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки. -Группа «Обозреватель каталога» позволяет искать и подсчитывать сущности, получать схему свойств и граф связей, разбирать запуски процессов и проверять готовность запуска без выполнения. Порядок настройки и примеры запросов — [в руководстве по обозревателю](catalog-explorer/). +При отказе инструмент возвращает `isError: true` с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос. ### curated_get_external_data