diff --git a/content/documentation/admin/ai-agents/external-agents.ru.md b/content/documentation/admin/ai-agents/external-agents.ru.md index da56ae6..a9919b9 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..edf8548 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-коллекции). +Для поиска, подсчёта и группировки сущностей, анализа связей и диагностики процессов добавьте группу «Обозреватель каталога» в 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-клиента. + ## Навыки агента -На той же вкладке назначьте [навыки](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..29faa9e 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..86a588d 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 и новые инструменты работы с каталогом. Коллекция может включать отдельные инструменты, серверы и группы портала целиком. - [Синхронизация внешних 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..1ed6d25 100644 --- a/content/documentation/user/ai-assistant.ru.md +++ b/content/documentation/user/ai-assistant.ru.md @@ -127,20 +127,44 @@ 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 сущности. Ответ зависит от заполненности каталога и записанных событий процесса. Одна лишь длительность запуска не подтверждает, что процесс завис. ## Работа с проектом Для задач с файлами прикрепите [рабочее пространство](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/mcp-management.ru.md b/content/documentation/user/mcp-management.ru.md index e22cee7..5bb772e 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-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера. + +«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Состав инструментов и примеры вызовов — [в справочнике MCP](mcp-server/#инструменты-работы-с-каталогом). «Курируемые» объединяет специализированные инструменты с префиксом `curated_`, включая запуск процессов, чтение навыков и подготовку рабочих пространств. Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией. @@ -148,5 +150,3 @@ MCP-коллекция объединяет инструменты и опред ## Настройка после обновления При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам. - -Часть прежних встроенных инструментов заменена [операциями с префиксом `ddp_`](mcp-server/#инструменты-операций-api). Обновите состав коллекций, сохранённые запросы MCP-клиентов и инструкции навыков. Для навыков агента проверьте доступность `get_skill`. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 68a3ec5..e4446ed 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -18,26 +18,26 @@ 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-коллекцию. -### Инструменты операций API +### Названия инструментов -Имя инструмента операции имеет вид `ddp_`. В «AI» → «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` | -| Прежнее имя | Актуальный инструмент | -| --- | --- | -| `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` | +Ниже приведены названия для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте `ddp_`; внешний агент может задавать собственное представление названий для модели. + +### Инструменты операций API + +В «AI» → «MCP» → «Каталог» отображаются названия инструментов, например `get_resources` и `get_resource_entities`, их описания и соответствующие HTTP-методы и пути API. По нажатию на название инструмента открывается схема его аргументов. Инструменты объединены в группы, например «Каталог», «Обозреватель каталога», «Действия», «Процессы и автоматизации» и «Рабочие пространства». Специализированные инструменты находятся в группе «Курируемые». -При переносе интеграции обновите имя и прочитайте `inputSchema` из `tools/list`: аргументы соответствуют операции API и могут отличаться от прежнего инструмента. Специализированные `get_processes`, `run_process` и `get_process_instance` сохраняют собственные имена и параметры. +Аргументы инструмента описаны в `inputSchema` ответа `tools/list`. Например, `run_process` — операция API, а `curated_run_process` — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются. Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например: @@ -50,9 +50,101 @@ MCP — это открытый протокол для взаимодейств } ``` -Для JSON тело передаётся как JSON. Для остальных форматов используется `encoding: "base64"`. Проверяйте `status` и тело ответа, в том числе при отказе в доступе и ошибках проверки входных данных. +Для 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`. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки. + +При отказе инструмент возвращает `isError: true` с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос. -### get_external_data +### curated_get_external_data Выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя. @@ -78,7 +170,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_processes +### curated_get_processes Получить список процессов с параметрами запуска. @@ -88,7 +180,7 @@ MCP — это открытый протокол для взаимодейств |---|---|---|---| | `include_step_properties` | булево | Нет | Вернуть также задачи процесса, которые принимают собственные значения параметров действия. По умолчанию выключено | -Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Схема элементов процесса не возвращается. +Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (`properties`) и пути контекста запуска, которые читает процесс (`contextPaths`). С `include_step_properties` — также задачи процесса с параметрами действий (`steps`). Поле `contextPathsComplete` показывает, учтены ли тела действий при сборе путей; перед подготовкой запуска запросите `include_step_properties: true`. Схема элементов процесса не возвращается. Пример: @@ -98,7 +190,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_service_templates +### curated_get_service_templates Получить шаблоны микросервисов из реестра шаблонов. @@ -118,7 +210,7 @@ MCP — это открытый протокол для взаимодейств --- -### run_process +### curated_run_process Запустить процесс для сущности. @@ -130,7 +222,7 @@ MCP — это открытый протокол для взаимодейств | `entity_uuid` | строка | Да | UUID сущности ресурса, к которому привязан процесс | | `properties` | объект | Да | Параметры запуска процесса: идентификатор параметра → значение. Не переданные параметры получают значения по умолчанию. Если задавать нечего, передайте `{}` | | `context` | объект | Нет | [Контекст запуска](../admin/processes/overview/#контекст-запуска), доступный в шаблонах процесса как `.context` | -| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `get_processes` с `include_step_properties` | +| `action_properties` | объект | Нет | Значения параметров действий задач: UUID задачи → объект «идентификатор параметра → значение». UUID задач и параметры возвращает `curated_get_processes` с `include_step_properties` | | `skipped_element_uuids` | массив | Нет | UUID элементов «AI-агент» и «Шаблон», которые пропускаются в этом запуске | | `agent_provider_refs` | объект | Нет | AI-провайдеры для элементов «AI-агент»: UUID элемента → название провайдера | @@ -147,7 +239,7 @@ MCP — это открытый протокол для взаимодейств --- -### get_process_instance +### curated_get_process_instance Получить один запуск процесса с хранилищем. @@ -156,7 +248,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 +265,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 +277,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 +353,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 +371,7 @@ Content-Type: application/json "content": [ { "type": "text", - "text": "[{\"uuid\":\"...\",\"name\":\"Service 1\",\"properties\":{...}},...]" + "text": "{\"status\":200,\"contentType\":\"application/json; charset=utf-8\",\"encoding\":\"json\",\"body\":{\"response\":[],\"error\":null}}" } ] } @@ -296,7 +388,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 секунд. + +Остановка рабочего пространства делает приложения недоступными; после запуска опубликованные адреса снова используются. Если после обновления шаблона появился текст «Адрес не зарезервирован текущей версией шаблона», отмените такую публикацию и опубликуйте порт в свободный адрес. + ## Задание агенту в чате Чтобы агент изменил проект: