# Прогрессивное раскрытие: CLI-окна в агентные системы

Canonical source: https://maguyva.ai/ru/blog/progressive-disclosure-cli-into-agents

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-20 · Author: Maguyva Team

> Агентные системы по умолчанию непрозрачны. Прогрессивное раскрытие даёт операторам многоуровневые CLI-представления — от быстрой проверки статуса до полного устройства агента и трасс решений.

> *Цифры в этом посте отражают состояние системы на момент публикации (январь 2026). Актуальные цифры смотрите на нашей [странице команды](/ru/team).*

Агентные системы непрозрачны по своей природе. Они принимают решения, вызывают инструменты и координируют работу десятков специалистов. Но когда что-то идёт не так — или когда вы просто хотите понять, что происходит, — куда смотреть?

Ответ — прогрессивное раскрытие: многоуровневый интерфейс, который открывает ровно столько сложности, сколько вам нужно, ровно тогда, когда это нужно.

## Проблема непрозрачности

Современная система оркестрации агентов может иметь:

- 40+ специализированных агентов, каждый со своими возможностями
- 700+ скиллов, охватывающих внутреннюю автоматизацию и интеграции с вендорами
- 470+ архитектурных решений, формирующих поведение
- Десятки MCP-серверов инструментов, предоставляющих внешние возможности

Эта сложность намеренная. Агентам нужен доступ к богатому контексту — доменным знаниям, интеллектуальному анализу кода, схемам БД, — чтобы принимать хорошие решения. Но то же богатство создаёт проблему видимости.

Как узнать, какой агент занимается миграциями БД? Какие решения сформировали поведение ранжирования в системе поиска? К каким инструментам имеет доступ архитектурный советник?

Без структурированного доступа вам остаётся читать исходный код или надеяться, что документация актуальна.

## Прогрессивное раскрытие как архитектура

Прогрессивное раскрытие — не просто паттерн UI. Это архитектурный принцип: организовать информацию слоями, каждый глубже предыдущего, чтобы пользователи могли остановиться на уровне, который отвечает на их вопрос.

Для агентных систем это превращается в CLI-команды возрастающей глубины:

| Уровень | Команда | На какой вопрос отвечает |
|-------|---------|-------------------|
| 1 | `orkestra system status` | Всё ли работает исправно? |
| 2 | `orkestra agents list` | Какие агенты существуют? |
| 3 | `orkestra agents info <name>` | Что делает этот агент? |
| 4 | `orkestra decisions search` | Почему это работает именно так? |
| 5 | MCP-инструменты Maguyva | Покажи мне код. |

Каждый уровень отвечает на естественный следующий вопрос. Вам редко нужно прыгать сразу на уровень 5.

## Уровень 1: работоспособность системы

Первый вопрос всегда: всё ли работает?

```bash
$ orkestra system status
```
```json
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}
```

Одна команда. Четыре цифры. Достаточно, чтобы знать, что система настроена, а реестры заполнены.

Если число агентов неожиданно падает или скиллы не загружаются, вы увидите это здесь первым делом. Не нужно нырять в логи.

## Уровень 2: инвентарь агентов

Как только вы знаете, что система работает исправно, следующий вопрос: что доступно?

```bash
$ orkestra agents list
```

Это возвращает структурированные данные — имена агентов, описания, предпочтения по модели, покрытие доменов. По умолчанию вывод в JSON, что легко направить через пайп в `jq` для фильтрации:

```bash
$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'
```

Нужны агенты, которые занимаются работой с БД? Команда поиска сужает круг:

```bash
$ orkestra agents search "database"
```

Это сканирует имена, описания и возможности. Вы находите нужного специалиста, не читая 40 определений агентов.

## Уровень 3: глубокое погружение в агента

Нашли агента, который выглядит подходящим? Команда `info` раскрывает всё:

```bash
$ orkestra agents info architecture-advisor
```

Вывод включает:

- **Метаданные**: имя, категорию, предпочтение по модели, описание
- **Домены**: какие области знаний покрывает этот агент
- **Личность (Identity)**: черты характера (architect, strategist, knowledge-architect)
- **Руководства по инструментам**: какая документация по инструментам внедряется в контекст
- **Инструменты**: полный список MCP-инструментов, доступных этому агенту

Вот пример того, что вы увидите:

```jsonc
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}
```

Это точно говорит вам, что может делать агент. Исходный код не требуется.

## Уровень 4: археология решений

Агенты ведут себя согласно задокументированным решениям. Когда вам нужно понять, *почему* что-то работает именно так, реестр решений — источник истины.

```bash
$ orkestra decisions search "agent"
```

Это возвращает совпадающие архитектурные решения:

```json
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}
```

У каждого решения есть полная история происхождения — когда оно было принято, почему, какие компромиссы рассматривались, какие коммиты его реализовали:

```bash
$ orkestra decisions info DEC-SR-049
```

```json
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}
```

Это архитектурная документация, которая остаётся актуальной, потому что добывается из коммитов, а не поддерживается вручную.

## Уровень 5: прямой интеллектуальный анализ кода

Когда вам нужно увидеть реальную реализацию — а не метаданные о ней, — MCP-инструменты Maguyva дают прямой доступ.

Изнутри сессии агента:

```
mcp__maguyva__intelligent_search
  query: "agent context loading"
```

Это автоматически маршрутизирует между семантическим, текстовым и AST-поиском, чтобы найти релевантный код. Для конкретных символов:

```
mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"
```

Для анализа зависимостей:

```
mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"
```

Эти инструменты не просто заменяют grep: они учитывают граф, используют семантический индекс и интегрированы с тем же интеллектуальным анализом кода, который питает самих агентов.

## Единый поиск по реестрам

Иногда вы не знаете, в каком реестре хранится ответ. Единый поиск охватывает всё:

```bash
$ orkestra search "database" --summary
```

```json
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}
```

254 совпадения по пяти реестрам. Сводка подсказывает, куда углубиться. Уберите `--summary` для детальных результатов или добавьте `--limit 5`, чтобы вывод оставался управляемым.

## Почему это важно

Прогрессивное раскрытие — не просто про удобство. Оно меняет то, как вы взаимодействуете со сложными системами.

**Отладка становится посильной.** Когда агент принимает неожиданное решение, вы не грепаете логи. Вы проверяете, к каким инструментам у него есть доступ (`agents info`), какие решения формируют его поведение (`decisions search`), и при необходимости прослеживаете реализацию (`intelligent_search`).

**Онбординг ускоряется.** Новым участникам команды не нужно читать всю кодовую базу. Они начинают с `system status`, исследуют с `agents list` и углубляются только тогда, когда натыкаются на что-то непонятное.

**Документация остаётся актуальной.** Поскольку CLI читает из тех же реестров, которые конфигурируют агентов, вывод всегда точен. Нет расхождения между тем, что говорит документация, и тем, что делает система.

## CLI как интерфейс

Мы могли бы построить веб-дашборд. Мы могли бы написать обширную документацию. Вместо этого мы построили CLI, который читает из источника истины.

У CLI есть преимущества:

- **Компонуемость**: пропускайте вывод через пайп в `jq`, интегрируйте со скриптами
- **Скриптуемость**: автоматизируйте проверки, генерируйте отчёты
- **Скорость**: никаких загрузок страниц, никаких потоков аутентификации
- **Точность**: читает реальную конфигурацию, а не кешированное представление

Для систем, где корректность важнее эстетики, побеждает CLI.

## Как построить своё прогрессивное раскрытие

Если вы строите агентные системы, продумайте, как пользователи будут их изучать:

1. **Начните с проверок работоспособности.** Одна команда, которая говорит, работает ли всё.
2. **Предоставьте инвентарные представления.** Перечислите, что существует, прежде чем объяснять, что оно делает.
3. **Обеспечьте целевые запросы.** Поиск побеждает просмотр в масштабе.
4. **Раскройте происхождение.** Дайте пользователям проследить решения до их истоков.
5. **Подключитесь к интеллектуальному анализу кода.** В конце концов, пользователям нужно увидеть реализацию.

Каждый слой отвечает на следующий вопрос. Стройте их в порядке частоты — большинство пользователей останавливаются на слое 2 или 3. Только продвинутые пользователи доходят до слоя 5.

Цель не в том, чтобы раскрыть всё. Цель в том, чтобы раскрыть ровно то, что нужно, ровно тогда, когда это нужно. Это и есть прогрессивное раскрытие, применённое к архитектуре агентов.