# PowerShell в Maguyva: графы кода для скриптов и модулей

Canonical source: https://maguyva.ai/ru/languages/powershell

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).

Maguyva поддерживает PowerShell с AST, символами и графом, чтобы ИИ-агенты могли прослеживать функции, классы и вызовы командлетов в скриптах и модулях.

## Сводка поддержки

- Уровень: Поддержка AST и символов
- Командные оболочки
- Расширения: .ps1, .psd1, .psm1
- Настоящий AST-разбор для синтаксически осведомлённого поиска и структурного контекста.
- Именованные символы обеспечивают семантический поиск и перекрёстные ссылки. Навигация по графу доступна, когда включено извлечение связей.
- Этот язык добавляет символы и связи в поиск с учётом графа; поддерживаемые типы рёбер зависят от присущих ему конструкций.
- Доступны и AST-разбор, и извлечение символов.

## Лучше всего подходит

- Команды инфраструктуры и эксплуатации с большими наборами `.ps1` и `.psm1`, где скрипты вызывают функции друг друга.
- Модули PowerShell, построенные из расширенных функций, классов и перечислений.
- Ранбуки автоматизации, где агенту нужно увидеть, какие скрипты затрагивают службу, общую папку или раздел реестра, прежде чем что-то менять.

## Сценарии работы агента

- Найти все вызовы расширенной функции, прежде чем менять её параметры.
- Перечислить скрипты, вызывающие командлет вроде `Restart-Service`, прежде чем менять ранбук.
- Составить карту функций, которые записывают в общую переменную, перед рефакторингом модуля.

## Где PowerShell сбивает с толку поверхностные ИИ-инструменты

Ваши функции и встроенные командлеты используют один стиль именования. `Get-Invoice` и `Get-ChildItem` выглядят одинаково, поэтому инструмент, отбрасывающий «встроенные» команды по глаголу, отбрасывает и ваши функции. Кроме того, скрипты смешивают код уровня модуля, функции, классы и блоки скриптов в одном файле, и трудно понять, какой функции принадлежит строка.

Maguyva сохраняет оба вида вызовов и приписывает каждый вызов функции, внутри которой он находится.

## Что Maguyva извлекает из кода PowerShell

Maguyva охватывает файлы `.ps1`, `.psm1` и `.psd1`. Функции и методы классов извлекаются как вызываемые объекты, а классы и перечисления как типы. Параметры скриптов и методов отслеживаются, а чтение и запись внутри функции приписываются этой функции, а не модулю.

Вызовы командлетов остаются в графе. PowerShell не применяет фильтр стандартной библиотеки, который используется для большинства языков, поэтому `Write-Host`, `Get-ChildItem` и `Restart-Service` отображаются как рёбра вызовов рядом с вашими функциями `Get-*` и `Set-*`. Агент может спросить, какие скрипты перезапускают службу или какие функции пишут в консоль, и получить структурный ответ.

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

## Примеры промптов для агентов

- «Кто вызывает `Invoke-Backup` и из каких запланированных скриптов?» (`find_symbol`, затем `dependency_search` по входящим связям)
- «Какие функции вызывают `Restart-Service`?» (`dependency_search`)
- «Проследи, что делает `Deploy-Site` от начала до конца.» (`get_task_context`)

## Известные ограничения

- Поскольку вызовы командлетов сохраняются, у очень распространённых командлетов, таких как `Write-Host` и `Select-Object`, много входящих рёбер. Когда нужен сфокусированный граф вызовов, начинайте с собственной функции.
- `Import-Module` и подключение скриптов через точку являются обычными командами, поэтому пресет `imports` в `structural_search` ничего не выбирает. Чтобы перечислить их, используйте `text_pattern_search`.

## Следующие шаги

Подключите репозиторий по [быстрому старту](/ru/docs/quickstart), затем изучите матрицу поддержки на [странице совместимости](/ru/docs/compatibility). Для кода .NET, который вызывают ваши скрипты, прочитайте [руководство по C#](/ru/languages/csharp).

## Детали движка

- Поддержка PowerShell охватывает файлы `.ps1`, `.psm1` и `.psd1`. Функции и методы классов являются вызываемыми объектами; классы и перечисления являются типами.
- Фильтр стандартной библиотеки для PowerShell отключён, поэтому вызовы командлетов вроде `Get-ChildItem` остаются в графе рядом с вашими функциями.
- Чтение и запись внутри функции приписываются этой функции, а не модулю.

## Полезные точки входа MCP

- `find_symbol`: Используйте для расширенной функции или класса, когда нужны определение и вызовы.
- `dependency_search`: Используйте обход входящих связей, чтобы увидеть, какие скрипты вызывают командлет вроде `Restart-Service`.
- `get_task_context`: Используйте для промптов вроде «проследи, что делает `Deploy-Site` от начала до конца».