# Maguyva 的 PowerShell 支援：面向腳本與模組的程式碼圖譜

Canonical source: https://maguyva.ai/zh-hant/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 以 AST、符號和圖譜支援 PowerShell，讓 AI 代理跨越腳本和模組追蹤函式、類別和 cmdlet 呼叫。

## 支援概況

- 等級: AST 與符號支援
- Shell
- 副檔名: .ps1, .psd1, .psm1
- 真正的 AST 剖析，支援語法感知搜尋與結構化情境。
- 具名符號支援語意查詢與交叉參照。啟用關係擷取後，即可使用圖譜導覽。
- 這個語言會為圖譜感知搜尋提供符號與關係；支援的邊類型會隨其原生構造而異。
- 同時支援 AST 剖析與符號擷取。

## 最適合的情境

- 擁有大量 `.ps1` 和 `.psm1` 資產、腳本之間相互呼叫函式的基礎設施與運維團隊。
- 由進階函式、類別和列舉建構的 PowerShell 模組。
- 在變更前需要讓代理看清哪些腳本會觸及某個服務、檔案共享或登錄機碼的自動化操作手冊。

## 代理工作流程

- 在修改進階函式的參數之前，找到它的所有呼叫端。
- 在修改操作手冊之前，列出呼叫 `Restart-Service` 等 cmdlet 的腳本。
- 在重構模組之前，梳理哪些函式會寫入某個共享變數。

## PowerShell 讓淺層 AI 工具栽跟頭的地方

你的函式和內建 cmdlet 共用同一種命名風格。`Get-Invoice` 和 `Get-ChildItem` 看起來一模一樣，所以按動詞剔除「內建命令」的工具會連你自己的函式一起扔掉。腳本還會把模組級程式碼、函式、類別和腳本塊混在一個檔案裡，很難判斷某一行屬於哪個函式。

Maguyva 會保留這兩類呼叫，並把每個呼叫歸屬到它所在的函式。

## Maguyva 在 PowerShell 中擷取什麼

Maguyva 支援 `.ps1`、`.psm1` 和 `.psd1` 檔案。函式和類別方法作為可呼叫物件擷取，類別和列舉作為型別擷取。腳本參數和方法參數都會被追蹤，函式內部的讀寫會歸屬到該函式，而不是模組。

cmdlet 呼叫會留在圖譜中。PowerShell 不使用大多數語言都會啟用的標準函式庫篩選器，因此 `Write-Host`、`Get-ChildItem` 和 `Restart-Service` 會作為呼叫邊出現在你自己的 `Get-*` 和 `Set-*` 函式旁邊。代理可以詢問哪些腳本會重啟某個服務、哪些函式會向主控台寫入，並得到基於結構的答案。

PowerShell 沒有被標記為不適用的關係型別，因此圖譜還會記錄類別繼承與介面實作、實例化、控制流以及讀寫。

## 代理提示範例

- 「誰呼叫了 `Invoke-Backup`，來自哪些排程腳本？」（先用 `find_symbol`，再用 `dependency_search` 的 incoming 方向）
- 「哪些函式呼叫了 `Restart-Service`？」（`dependency_search`）
- 「從頭到尾追蹤 `Deploy-Site` 做了什麼。」（`get_task_context`）

## 已知限制

- 由於 cmdlet 呼叫會被保留，`Write-Host` 和 `Select-Object` 等非常常見的呼叫會有大量傳入邊。想要聚焦的呼叫圖時，請從你自己的函式入手。
- `Import-Module` 和點源載入都是普通命令，因此 `structural_search` 中的 `imports` 預設集什麼也選不到。列出它們請使用 `text_pattern_search`。

## 下一步

透過[快速入門](/zh-hant/docs/quickstart)連接儲存庫，然後在[相容性頁面](/zh-hant/docs/compatibility)檢視支援矩陣。腳本所呼叫的 .NET 程式碼請閱讀 [C# 指南](/zh-hant/languages/csharp)。

## 引擎細節

- PowerShell 支援涵蓋 `.ps1`、`.psm1` 和 `.psd1`。函式和類別方法是可呼叫物件，類別和列舉是型別。
- PowerShell 關閉了標準函式庫篩選器，因此 `Get-ChildItem` 等 cmdlet 呼叫會和你自己的函式一起留在圖譜中。
- 函式內部的讀寫會歸屬到該函式，而不是模組。

## 實用的 MCP 進入點

- `find_symbol`: 需要進階函式或類別的定義和呼叫端時使用它。
- `dependency_search`: 對 `Restart-Service` 等 cmdlet 使用 incoming 方向走訪，檢視哪些腳本呼叫了它。
- `get_task_context`: 用於「從頭到尾追蹤 `Deploy-Site` 做了什麼」這類提示。