# Maguyva 對 Python 的支援：AI 程式碼搜尋與重構

Canonical source: https://maguyva.ai/zh-hant/languages/python

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 剖析與符號擷取支援 Python，協助 AI 代理在真實的 Python 儲存庫中，追蹤裝飾器、self／cls 方法、引入項目與跨模組依賴關係。

## 支援概況

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

## 最適合的情境

- 應用程式碼與維運腳本並存的 FastAPI、Django、資料平台或內部工具儲存庫。
- 重構已擁有裝飾器、背景工作與大量隱含連結的長壽命 Python 服務的團隊。
- 在變更 handler、service、model 或輔助函式之前，需要不只是 grep 的代理工作流程。

## 代理工作流程

- 在編輯之前，先追蹤一個端點、工作或 CLI 指令，穿過輔助函式與共用模組。
- 找出某個 service、類別或工具函式，在整個儲存庫中於何處被實例化與重複使用。
- 比較相鄰的實作方式，確保代理編輯的是正確的抽象層，而不是字面上最相近的字串。

## Python 儲存庫通常會讓淺層 AI 工具破功的地方

Python 正是許多 AI 編碼工具，一開始看起來表現不錯、進了正式環境卻開始亂猜的地方。困難的部分大家都很熟悉：加了裝飾器的進入點、service 類別、型別存根、到處都是的小型輔助模組，以及只有在你把 `self` 或 `cls` 重新連回它所屬的類別後，才真正說得通的方法。

對 Python 而言，真正的問題不是「它能不能讀 `.py` 檔案？」，而是代理能否在從一個端點移動到一個 service、從一項背景工作移動到一個輔助函式、或從一個類別名稱移動到真正實作該行為的方法時，始終以實際程式碼為依據。

## Maguyva 在 Python 中實際擷取了什麼

Maguyva 為 Python 提供完整的結構分析支援。這份設定涵蓋 `.py`、`.pyw` 與 `.pyi`；會將 `decorated_definition` 對應回一個函式符號；並為 `self`／`cls` 方法呼叫補上所屬類別的限定名稱。這一點很重要，因為這些正是 Python 儲存庫對人類來說一目瞭然、對 LLM 來說卻變得模糊不清的關鍵之處。

它同時也從關係擷取中過濾掉大量標準函式庫雜訊。這代表來自像 `pathlib`、`typing` 或 `logging` 這類模組的常見執行環境呼叫，比較不容易淹沒你真正在乎的、儲存庫本身特有的關係。

## 對 Python 儲存庫有用的 MCP 工作流程

最簡單、最有效的工作流程是：

- 針對行為層面的問題，例如「發票同步周邊的重試邏輯」或「計費端點中的權限檢查」，從 `intelligent_search` 開始。
- 一旦你已知在乎的類別或函式名稱，就切換到 `find_symbol`。
- 在重構一個共用 service、輔助函式或基底類別之前，搭配傳入方向的追蹤使用 `dependency_search`。

這樣的模式，遠比從零開始要求代理「更新計費流程」要好得多。它讓代理先建構出一份地圖，再動手變更程式碼。

## 這個頁面適合什麼情境

這個頁面適合已經具備一定年資與複雜度的 Python 儲存庫：service 程式碼、排程工作、腳本、自動生成的型別，以及周邊設定。如果你主要比較的對象是多語言的 Web 單一儲存庫，也可以參閱 [TypeScript 指南](/zh-hant/languages/typescript)。如果你只需要完整的支援矩陣，請參閱 [相容性](/zh-hant/docs/compatibility)。

## 引擎細節

- 加了裝飾器的定義，仍然被視為函式，因此加了裝飾器的 view 與 task 依然可以用符號來搜尋。
- `self` 與 `cls` 的方法呼叫，會補上所屬類別的限定名稱，這有助於在大量使用類別的服務程式碼中，讓圖譜保持有用。
- 已啟用 import、呼叫與符號的正規化，同時像 `pathlib.*`、`typing.*` 與 `logging.*` 這類常見的標準函式庫雜訊，則會從關係中被過濾掉。

## 實用的 MCP 進入點

- `intelligent_search`: 先從像是「發票同步周圍的重試邏輯」這種概念性查詢開始，如果儲存庫是多語言混合的，就設定 `language_filter="python"`。
- `find_symbol`: 當你知道類別或函式名稱，並且在編輯前需要定義加上參照時使用。
- `dependency_search`: 在重構共用的服務或輔助函式之前，使用傳入方向，看看有哪些東西依賴它。