# Maguyva 對 Swift 的支援：iOS 與 macOS 的程式碼圖譜

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

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、符號與圖譜支援 Swift，讓 AI 代理能在 iOS 與 macOS 程式碼中追蹤協定、擴充、初始化器與屬性觀察器。

## 支援概況

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

## 最適合的情境

- 擁有大型應用程式 target 與共用 Swift 套件的 iOS 與 macOS 團隊。
- 圍繞協定與擴充打造的程式碼庫，一個型別的行為分散在許多檔案中。
- 在變更共用模型、服務或協定之前需要影響分析的代理工作流程。

## 代理工作流程

- 在變更協定要求之前，找出所有遵循該協定的型別。
- 跨越 ViewModel、協調器與套件，追蹤某個服務方法的呼叫端。
- 找出會碰到某個狀態的初始化器、計算屬性與 `didSet` 觀察器。

## 為什麼 Swift 需要的不只是檔案搜尋

Swift 會把一個型別分散到許多地方。一個結構在某個檔案中宣告，從另外三個檔案的擴充取得行為，並遵循某個套件中定義的協定。狀態變化藏在計算屬性與 `willSet` / `didSet` 觀察器裡。一次只讀一個檔案的代理會漏掉其中大部分。

Maguyva 會為這些結構建立索引，讓代理能一併看到一個型別的成員、協定遵循與呼叫端。

## Maguyva 在 Swift 中擷取了什麼

Maguyva 涵蓋 `.swift`。可呼叫的符號包括函式、`init` 與 `deinit`、下標、計算屬性的 getter 與 setter，以及 `willSet` / `didSet` 觀察器，因此改變狀態的程式碼可以作為符號搜尋，而不會埋在屬性本體中。

在結構、列舉、協定與擴充中宣告的成員，會以所屬型別限定（例如 `CartStore.add`），在擴充中新增的成員則歸屬到被擴充的型別。定義名稱會移除泛型參數、協定遵循清單，以及 `?` / `!` 後綴，因此查找時使用的是單純的名稱。呼叫會保留 `self.` 與類別限定，尾隨閉包也會計入呼叫的引數數量。

圖譜會記錄呼叫、協定遵循、繼承、覆寫、實例化、屬性標記（attribute）、型別參照、讀寫，以及 `throw` 邊。

## 代理提示範例

- 「哪些型別遵循 `PaymentProvider`，它們各自在哪裡建立？」（`dependency_search`）
- 「誰呼叫了 `CartStore.add`，來自哪些視圖？」（先用 `find_symbol`，再用 `dependency_search` 的 incoming 方向）
- 「說明一則推播通知是如何抵達收件匣畫面的。」（`get_task_context`）

## 已知限制

- 只有 `.swift` 原始碼會被對應。Storyboard 與 XIB 檔案不在副檔名清單中，因此 Interface Builder 中的連結不在圖譜範圍內。
- `print`、`debugPrint`、`NSLog` 與斷言等標準函式庫與 Foundation 呼叫會從關係中過濾掉，因此它們不是圖譜的邊。查找它們請使用 `text_pattern_search`。

## 下一步

透過[快速入門](/zh-hant/docs/quickstart)連接儲存庫，然後在[相容性頁面](/zh-hant/docs/compatibility)查看支援矩陣。如果同一款產品也在 Android 上推出，請閱讀 [Kotlin 指南](/zh-hant/languages/kotlin)。

## 引擎細節

- 可呼叫的符號包括函式、`init`、`deinit`、下標、計算屬性的 getter 與 setter，以及 `willSet` / `didSet` 觀察器。
- 結構、列舉、協定與擴充的成員會以所屬型別限定，例如 `CartStore.add`。
- 定義名稱會移除泛型參數、協定遵循清單與 `?` / `!` 後綴，呼叫會保留 `self.` 與類別限定。

## 實用的 MCP 進入點

- `find_symbol`: 需要定義與參照時，以型別、協定或方法名稱查找。
- `dependency_search`: 對協定使用它，可找到遵循它的型別；對方法以 incoming 方向使用，可找到呼叫端。
- `get_task_context`: 適合用於「說明一則推播通知是如何抵達收件匣畫面的」這類提示。