diff --git a/content/documentation/admin/actions/types.ru.md b/content/documentation/admin/actions/types.ru.md index 781af1e..7cce4c8 100644 --- a/content/documentation/admin/actions/types.ru.md +++ b/content/documentation/admin/actions/types.ru.md @@ -711,7 +711,7 @@ createContent: false Пример файла `.templateignore` для игнорирования содержимого директорий `helm`, `docs`: -```text +```sh helm/** docs/** ``` @@ -720,7 +720,7 @@ docs/** ### Пример структуры директорий шаблонного репозитория -```text +```sh ├── example-folder-01 │ ├── example-file-01 │ └── {{ .example }}-file-02 @@ -732,7 +732,7 @@ docs/** Если переменная **example** при рендере репозитория примет значение **new**, то итоговая структура после рендера будет выглядеть следующим образом: -```text +```sh ├── example-folder-01 │ ├── example-file-01 │ └── new-file-02 diff --git a/content/documentation/admin/datasources/types.ru.md b/content/documentation/admin/datasources/types.ru.md index d862975..2b57775 100644 --- a/content/documentation/admin/datasources/types.ru.md +++ b/content/documentation/admin/datasources/types.ru.md @@ -668,19 +668,19 @@ GenericAPI поддерживает любые типы аутентификац **Bearer Token:** -```text +```sh Authorization: Bearer <токен> ``` **Basic Authentication:** -```text +```sh Authorization: Basic ``` **API Key:** -```text +```sh X-API-Key: <ключ> ``` diff --git a/content/documentation/admin/external-services.ru.md b/content/documentation/admin/external-services.ru.md index 2c4f7dd..c40f0d2 100644 --- a/content/documentation/admin/external-services.ru.md +++ b/content/documentation/admin/external-services.ru.md @@ -81,7 +81,7 @@ moduleStatus: experimental **Пример:** -```text +```sh Authorization: <ваш-api-token> ``` @@ -97,11 +97,11 @@ Authorization: <ваш-api-token> **Пример:** -```text +```sh Authorization: Token <ваш-defectdojo-api-v2-key> ``` -Подробнее о том, как получить API v2 Key токен можно узнать в [официальной документации Defectdojo](https://docs.defectdojo.com/en/api/api-v2-docs/). +Подробнее о том, как получить API v2 Key токен можно узнать в [официальной документации](https://docs.defectdojo.com/en/api/api-v2-docs/). ### Docker Registry @@ -119,7 +119,7 @@ Authorization: Token <ваш-defectdojo-api-v2-key> 2. Закодируйте её в Base64: `echo "username:password" | base64` 3. Добавьте заголовок: -```text +```sh Authorization: Basic ``` @@ -135,7 +135,7 @@ Authorization: Basic **Пример:** -```text +```sh Private-Token: <ваш-gitlab-token> ``` @@ -157,7 +157,7 @@ Private-Token: <ваш-gitlab-token> 2. Закодируйте её в Base64: `echo "username:password" | base64` 3. Добавьте заголовок: -```text +```sh Authorization: Basic ``` @@ -173,7 +173,7 @@ Authorization: Basic **Пример:** -```text +```sh Authorization: <ваш-kaiten-api-token> ``` @@ -189,7 +189,7 @@ Authorization: <ваш-kaiten-api-token> **Пример:** -```text +```sh Authorization: Bearer <ваш-kubernetes-token> ``` @@ -209,7 +209,7 @@ Authorization: Bearer <ваш-kubernetes-token> 2. Закодируйте её в Base64: `echo "username:password" | base64` 3. Добавьте заголовок: -```text +```sh Authorization: Basic ``` @@ -229,7 +229,7 @@ Authorization: Basic 2. Закодируйте её в Base64: `echo "username:password" | base64` 3. Добавьте заголовок: -```text +```sh Authorization: Basic ``` @@ -245,13 +245,13 @@ Authorization: Basic **Пример Bearer Token:** -```text +```sh Authorization: Bearer <ваш-токен> ``` **Пример Basic Authentication:** -```text +```sh Authorization: Basic ``` @@ -267,6 +267,6 @@ Authorization: Basic **Пример:** -```text +```sh Authorization: Bearer <ваш-токен> ``` diff --git a/content/documentation/admin/security/http-security-headers.ru.md b/content/documentation/admin/security/http-security-headers.ru.md index d69eacc..de2ee10 100644 --- a/content/documentation/admin/security/http-security-headers.ru.md +++ b/content/documentation/admin/security/http-security-headers.ru.md @@ -72,7 +72,7 @@ Content Security Policy (CSP) — это механизм безопасност ### CSP по умолчанию -```text +```sh default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; diff --git a/content/documentation/admin/widgets/types.ru.md b/content/documentation/admin/widgets/types.ru.md index 40cbdbe..99e1fd7 100644 --- a/content/documentation/admin/widgets/types.ru.md +++ b/content/documentation/admin/widgets/types.ru.md @@ -610,7 +610,7 @@ title: Типы виджетов Пример корректного запроса для виджета: -```text +```sh rate(nginx_ingress_controller_nginx_process_connections[5m]) ``` @@ -645,7 +645,7 @@ rate(nginx_ingress_controller_nginx_process_connections[5m]) Пример корректной query для виджета: -```text +```sh sum(ingress_nginx_detail_requests_total) ``` diff --git a/content/documentation/user/ai-agent.ru.md b/content/documentation/user/ai-agent.ru.md index 5010a61..1a69dc5 100644 --- a/content/documentation/user/ai-agent.ru.md +++ b/content/documentation/user/ai-agent.ru.md @@ -43,7 +43,7 @@ AI-агент использует настраиваемые AI-провайд Вместо прямого указания токена в заголовках провайдера используйте синтаксис шаблонизации: -```text +```sh Authorization: Bearer {{ .credentials.api_key }} ``` @@ -53,13 +53,13 @@ Authorization: Bearer {{ .credentials.api_key }} Вместо: -```text +```sh Authorization: Bearer sk-1234567890abcdef ``` Используйте: -```text +```sh Authorization: Bearer {{ .credentials.openai_api_key }} ``` @@ -87,7 +87,7 @@ Authorization: Bearer {{ .credentials.openai_api_key }} - **Метод**: `POST`. - **Заголовки**: добавьте заголовок авторизации, используя учетные данные: - ```text + ```sh Authorization: Bearer {{ .credentials.openai_api_key }} ``` @@ -208,7 +208,7 @@ choices.0.message.content 1. **Метод**: `POST`. 1. **Заголовки**: - ```text + ```sh Authorization: Bearer {{ .credentials.api_key }} Content-Type: application/json ``` @@ -246,11 +246,9 @@ AI-агент доступен через боковую панель чата AI-агент использует инструменты MCP (Model Context Protocol) для работы с платформой. Полный список доступных инструментов с их описанием, параметрами и примерами использования доступен в [документации MCP-сервера](../mcp-server/). -**Основные возможности:** -- Получение списка ресурсов и их сущностей. -- Просмотр доступных действий для ресурсов и сущностей. -- Информация об источниках данных. -- Самостоятельное управление ресурсами и их сущностями (self-service). +Основные возможности инструментов: +- Получение и анализ данных из каталога платформы. +- Консультации по документации платформы. ### Просмотр доступных инструментов @@ -262,35 +260,7 @@ AI-агент использует инструменты MCP (Model Context Pro ### Формулирование вопросов -Вы можете задавать вопросы AI-агенту в свободной форме на естественном языке. Агент автоматически определит, какие инструменты использовать, и выполнит запрос. - -**Типы вопросов:** - -- **Анализ данных**: «Сколько сервисов в статусе разработки?», «Покажи все сервисы с ошибками». -- **Работа с каталогом**: «Найди все сервисы, где жизненный цикл равен production». -- **Фильтрация и подсчет**: «Сколько сущностей в ресурсе Deckhouse Code». -- **Комплексные запросы**: «Покажи все ресурсы и для каждого покажи количество сущностей». - -### Форматы вывода - -Вы можете указать, в каком формате хотите получить данные: - -- **Таблица** (по умолчанию) — данные выводятся в виде таблицы. -- **Список** — данные выводятся в виде списка. - -**Примеры:** -- «Покажи ресурсы списком». -- «Выведи действия таблицей». -- «Покажи ресурсы с полями name и slug». - -### Мультизапросы - -AI-агент может автоматически вызывать несколько инструментов последовательно для выполнения сложных запросов. Это происходит автоматически, когда для ответа на вопрос требуется информация из нескольких источников. - -**Примеры мультизапросов:** - -- «Покажи все ресурсы и для каждого покажи количество сущностей». - - Агент сначала получит список ресурсов, затем для каждого ресурса получит сущности и подсчитает их количество. +Вы можете задавать вопросы AI-агенту в свободной форме: - **Вопросы о платформе**: «Как создать новое действие?», «Как настроить автоматизацию?». - **Анализ данных**: «Сколько сервисов в статусе разработки?», «Покажи все сервисы с ошибками». @@ -301,19 +271,9 @@ AI-агент автоматически определит, какой инст ### Особенности работы 1. **Анализ данных**: AI-агент не просто возвращает сырые данные, а анализирует их и предоставляет структурированные ответы. -1. **Фильтрация**: Вы можете запрашивать данные с условиями, и агент выполнит фильтрацию. Например: «Найди все сервисы, у которых параметр 'Жизненный цикл' равен 'разработка'». -1. **Агрегация**: Агент может подсчитывать количество, группировать данные и предоставлять статистику. Например: «Сколько сервисов в продакшене?» или «Посчитай количество сервисов в разработке». +1. **Фильтрация**: Вы можете запрашивать данные с условиями, и агент выполнит фильтрацию. +1, **Агрегация**: Агент может подсчитывать количество, группировать данные и предоставлять статистику. 1. **Контекст документации**: При вопросах о платформе агент использует официальную документацию. -1. **Творческие запросы**: Вы можете попросить агента создать творческий контент на основе данных. Например: «Опиши красиво все сервисы". - -### Обработка результатов - -После получения данных от инструментов система автоматически обрабатывает результаты: - -- **Простые запросы** («покажи», «выведи») — данные отображаются в виде форматированных таблиц или списков. -- **Аналитические запросы** (фильтрация, подсчет, сравнение) — данные анализируются, и возвращается только нужный результат. - -> **Важно:** AI-агент никогда не показывает весь массив данных пользователю. Вместо этого он анализирует данные и возвращает только нужную информацию (например, количество найденных элементов или отфильтрованный список). ### Отладка @@ -321,88 +281,14 @@ AI-агент автоматически определит, какой инст ## Примеры использования -### Базовые запросы - -**Получение списка ресурсов:** - -```text -"Покажи все ресурсы" -"Выведи ресурсы таблицей" -"Покажи ресурсы списком" -``` - -**Получение сущностей ресурса:** - -```text -"Получи все сервисы" -"Покажи все сущности ресурса 'Сервисы'" -"Найди все репозитории" -``` - -**Получение действий:** - -```text -"Какие действия можно выполнить для сервисов?" -"Покажи действия для сервисов списком" -"Что можно сделать с сервисом 'my-service'?" -``` - -**Получение источников данных:** - -```text -"Какие источники данных синхронизируют данные в ресурс 'Сервисы'?" -"Покажи источники данных для сервисов" -``` - -**Возможности самостоятельного управления (self-service):** - -```text -"Что я могу сделать для сервисов?" -"Какие self-service возможности есть?" -"Покажи все возможности для объекта 'backend-service'" -``` - -### Запросы с фильтрацией - -**Фильтрация по параметрам:** - -```text -"Найди все сервисы, у которых параметр 'Жизненный цикл' равен 'разработка'" -``` - -**Подсчет и статистика:** - -```text -"Сколько всего сервисов?" -"Посчитай количество сервисов в разработке" -"Сколько действий доступно для сервисов?" -``` - -### Комплексные запросы (мультизапросы) - -**Комбинирование данных:** - -```text -"Покажи все ресурсы и для каждого покажи количество сущностей" -"Что можно сделать для сервисов и какие источники данных их синхронизируют?" -"Получи информацию о сервисе 'my-service': его действия и возможности" -``` - ### Пример 1: Анализ сервисов **Вопрос:** -```text +```sh Получи все сервисы, найди те, у которых параметр 'Жизненный цикл' равен 'разработка', и выведи их количество ``` -**Как это работает:** -1. AI-агент вызывает инструмент для получения всех сервисов. -2. Получает массив всех сервисов. -3. Фильтрует сервисы, где параметр «Жизненный цикл» равен «разработка». -4. Подсчитывает количество найденных сервисов. -5. Возвращает результат: «Найдено 15 сервисов в разработке» (без показа всех данных). - **Результат:** Агент использует инструменты MCP для получения данных о сервисах, проанализирует их и вернет количество сервисов в разработке. @@ -410,55 +296,15 @@ AI-агент автоматически определит, какой инст **Вопрос:** -```text +```sh Покажи все сервисы с ошибками и основные причины ошибок ``` -**Как это работает:** -1. AI-агент получает все сервисы. -1. Анализирует статус здоровья каждого сервиса. -1. Находит сервисы с ошибками. -1. Извлекает информацию о причинах ошибок. -1. Формирует структурированный список. - **Результат:** Агент получит данные о сервисах, проанализирует их статусы, найдет ошибки и предоставит структурированный список с причинами. -### Пример 3: Мультизапрос - -**Вопрос:** - -```text -Покажи все ресурсы и для каждого покажи количество сущностей -``` - -**Как это работает:** -1. AI-агент вызывает инструмент для получения списка ресурсов. -1. Для каждого ресурса вызывает инструмент для получения сущностей. -1. Подсчитывает количество сущностей для каждого ресурса. -1. Формирует итоговую таблицу или список. - -**Результат:** -Агент вернет список всех ресурсов с указанием количества сущностей в каждом, например: "Найдено 5 ресурсов: Сервисы (15 сущностей), Окружения (8 сущностей)..." - ## Рекомендации -### ✅ Рекомендуется - -1. **Используйте конкретные вопросы**: Чем конкретнее вопрос, тем точнее будет ответ. Вместо «что ты умеешь?» лучше спросить «что можно сделать для сервисов?». - -1. **Указывайте параметры явно**: Если вы знаете название ресурса или параметр, укажите его в вопросе. Например: «Найди все сервисы, где 'Жизненный цикл' равен 'разработка'». - -1. **Указывайте формат вывода**: Если нужен список, скажите «списком», если таблица — «таблицей». - -1. **Задавайте комплексные вопросы**: Система сама определит, какие инструменты использовать. Не нужно указывать технические детали. - +1. **Используйте конкретные вопросы**: Чем конкретнее вопрос, тем точнее будет ответ. +1. **Указывайте параметры явно**: Если вы знаете название ресурса или параметр, укажите его в вопросе. 1. **Экспериментируйте**: AI-агент понимает естественный язык, пробуйте разные формулировки вопросов. - -### ❌ Не рекомендуется - -1. **Слишком общие вопросы**: «Что ты умеешь?» лучше заменить на «Что можно сделать для сервисов?». - -1. **Технические детали**: Не нужно указывать точные имена инструментов, просто опишите задачу. - -1. **Множественные уточнения**: Задавайте один вопрос за раз. diff --git a/content/documentation/user/mcp-server.ru.md b/content/documentation/user/mcp-server.ru.md index 2c8f4e9..344a688 100644 --- a/content/documentation/user/mcp-server.ru.md +++ b/content/documentation/user/mcp-server.ru.md @@ -13,52 +13,22 @@ MCP — это открытый протокол для взаимодейств ## Доступные инструменты -### get_resources - -Получение списка всех ресурсов в платформе. - -**Параметры:** - -| Название | Тип | Описание | Примеры | -|----------|-----|----------|---------| -| Нет параметров | - | Инструмент не требует параметров | - | - -**Описание:** -Инструмент возвращает список всех доступных ресурсов в платформе. Ресурс — это тип объекта (например, «Сервисы», «Окружения», «Команды»). - -**Пример использования:** - -```text -Покажи все ресурсы -``` - -```text -Выведи ресурсы таблицей -``` - -```text -Покажи ресурсы списком -``` - -**Возвращаемые данные:** -- Массив ресурсов с информацией о каждом ресурсе (название, идентификатор (slug), описание). - ### get_resource_entities Получение всех сущностей указанного ресурса со всеми их свойствами и данными для анализа и агрегации. **Параметры:** -| Название | Тип | Описание | Примеры | -|-------------------------|--------|------------------------------------|---------------------------------------------------| -| `resource_name_or_slug` | строка | Название или идентификатор ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | +| Название | Тип | Описание | Примеры | +|-------------------------|--------|---------------------------|---------------------------------------------------| +| `resource_name_or_slug` | строка | Название или slug ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | **Описание:** Инструмент возвращает полный список сущностей указанного ресурса с их свойствами, метаданными, связями и другой информацией. Данные можно использовать для анализа, фильтрации, агрегации и построения отчетов. **Пример использования:** -```text +```sh Получи все сервисы, найди те, у которых параметр 'Жизненный цикл' равен 'разработка', и выведи их в таблицу формата 'название сервиса | жизненный цикл | дата создания' ``` @@ -69,137 +39,6 @@ MCP — это открытый протокол для взаимодейств - Связи с другими сущностями (родители, дочерние элементы). - Статус сущностей (health status). -{{< alert level="info" >}} -Этот инструмент возвращает все сущности ресурса. AI-агент автоматически анализирует данные и возвращает только нужный результат (например, количество найденных элементов или отфильтрованный список), а не весь массив данных. -{{< /alert >}} - -### get_actions_for_resource - -Получение списка всех действий, которые можно выполнить для объектов конкретного ресурса. - -**Параметры:** - -| Название | Тип | Описание | Примеры | -|-------------------------|--------|------------------------------------|---------------------------------------------------| -| `resource_name_or_slug` | строка | Название или идентификатор ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | - -**Описание:** -Инструмент возвращает список всех действий, доступных для выполнения с объектами указанного ресурса. - -**Пример использования:** - -```text -Какие действия можно выполнить для сервисов? -``` - -```text -Покажи действия для сервисов списком -``` - -```text -Выведи действия для ресурса 'Сервисы' таблицей -``` - -**Возвращаемые данные:** -- Массив действий с информацией о каждом действии (название, описание, параметры). - -### get_actions_for_entity - -Получение всех действий, которые можно выполнить для конкретной сущности. - -**Параметры:** - -| Название | Тип | Описание | Примеры | -|-------------------------|--------|-------------------------------------|---------------------------------------------------| -| `resource_name_or_slug` | строка | Название или идентификатор ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | -| `entity_name_or_slug` | строка | Название или идентификатор сущности | `my-service`, `backend-service` | - -**Описание:** -Инструмент возвращает все действия, которые можно выполнить для конкретной сущности. Включает проверку ограничений, зависящих от текущего состояния объекта. - -**Пример использования:** - -```text -Какие действия доступны для сервиса 'my-service'? -``` - -```text -Что можно сделать с сервисом 'backend-service'? -``` - -```text -Покажи действия для объекта 'my-app' в ресурсе 'Приложения' -``` - -**Возвращаемые данные:** -- Массив действий с информацией о каждом действии (название, описание, параметры, доступность). - -### get_datasources_for_resource - -Получение списка всех источников данных, которые синхронизируют данные в конкретный ресурс. - -**Параметры:** - -| Название | Тип | Описание | Примеры | -|-------------------------|--------|------------------------------------|---------------------------------------------------| -| `resource_name_or_slug` | строка | Название или идентификатор ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | - -**Описание:** -Инструмент возвращает список всех источников данных, которые синхронизируют данные в указанный ресурс. - -**Пример использования:** - -```text -Какие источники данных синхронизируют данные в ресурс 'Сервисы'? -``` - -```text -Покажи источники данных для сервисов -``` - -```text -Какие внешние системы синхронизируют данные в 'Сервисы'? -``` - -**Возвращаемые данные:** -- Массив источников данных с информацией о каждом источнике (название, тип, описание). - -### get_self_service_capabilities - -Получение полной информации о возможнстях самостоятельного управления (self-service) возможностях для ресурса или сущности. - -**Параметры:** - -| Название | Тип | Описание | Примеры | -|-------------------------|--------|---------------------------------------------------|---------------------------------------------------| -| `resource_name_or_slug` | строка | Название или идентификатор ресурса | `Сервисы`, `services`, `Deckhouse Code: Repositories` | -| `entity_name_or_slug` | строка | (опционально) Название или идентификатор сущности | `my-service`, `backend-service` | - -**Описание:** -Инструмент возвращает полную информацию о возможностях самостоятельного управления для ресурса или сущности. Возвращает список доступных действий и источников данных для синхронизации. - -**Пример использования:** - -```text -Что я могу сделать для сервисов? -``` - -```text -Какие self-service возможности есть для сервисов? -``` - -```text -Что можно сделать с сервисом 'my-service'? -``` - -```text -Покажи все возможности для объекта 'backend-service' -``` - -**Возвращаемые данные:** -- Список доступных действий для ресурса или сущности. -- Список источников данных для синхронизации. - ### get_external_data Выполнение HTTP-запроса к внешнему сервису с использованием учетных данных пользователя. @@ -208,7 +47,7 @@ MCP — это открытый протокол для взаимодейств | Название | Тип | Описание | Примеры | |-------------------------|--------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| -| `external_service_name` | строка | Название внешнего сервиса. Будет выполнен поиск по имени или идентификатор сервиса | `sonarqube`, `gitlab`, `kubernetes` | +| `external_service_name` | строка | Название внешнего сервиса. Будет выполнен поиск по имени или slug сервиса | `sonarqube`, `gitlab`, `kubernetes` | | `query` | строка | Описание запроса | `get pipelines for project 123`, `get sonarqube projects`, `get all namespaces` | | `api_path` | строка | Путь к API-эндпоинт с параметрами запроса. Генерируется моделью на основе `query` и `external_service_name` | `/api/v4/projects?per_page=100&page=1` | | `method` | строка | HTTP-метод. По умолчанию: GET. Модель определяет правильный метод на основе `query` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` | @@ -229,19 +68,19 @@ MCP — это открытый протокол для взаимодейств **Примеры использования:** -```text +```sh Получи все namespaces из внешнего сервиса Kubernetes ``` -```text +```sh Получи список проектов из SonarQube ``` -```text +```sh Получи все pipelines для GitLab проекта с ID 123 ``` -```text +```sh Создай merge request в GitLab для проекта 456 с веткой feature/new-feature ``` @@ -312,22 +151,12 @@ MCP — это открытый протокол для взаимодейств - Сохраните конфигурацию. - LM Studio попытается подключиться к серверу. - Если подключение успешно, вы увидите список доступных инструментов: - - `get_resources`. - - `get_resource_entities`. - - `get_actions_for_resource`. - - `get_actions_for_entity`. - - `get_datasources_for_resource`. - - `get_self_service_capabilities`. - - `get_external_data`. + - `get_resource_entities` + - `get_external_data` После успешного подключения вы можете использовать инструменты в диалогах с моделями: -- `get_resources` для получения списка всех ресурсов. -- `get_resource_entities` для получения данных о сущностях ресурса. -- `get_actions_for_resource` для получения действий, доступных для ресурса. -- `get_actions_for_entity` для получения действий, доступных для конкретной сущности. -- `get_datasources_for_resource` для получения источников данных ресурса. -- `get_self_service_capabilities` для получения полной информации о возможностях самостоятельного управления. +- `get_resource_entities` для получения данных о ресурсах. - `get_external_data` для выполнения запросов к внешним сервисам (GitLab, SonarQube, Kubernetes и др.). Все вызовы будут выполняться с вашими правами доступа. @@ -349,7 +178,7 @@ MCP-сервер Deckhouse Development Platform совместим с любым **HTTP-заголовки:** -```text +```sh X-API-TOKEN: your-api-token-here Content-Type: application/json ``` @@ -418,7 +247,7 @@ Content-Type: application/json ### Инструмент возвращает ошибку доступа - Убедитесь, что у вашего пользователя есть права на доступ к запрашиваемому ресурсу. -- Проверьте правильность имени или идентификатор ресурса. +- Проверьте правильность имени или slug ресурса. - Обратитесь к администратору платформы для проверки прав доступа. ### Данные не возвращаются