# Maguyva 的 Swift 支持：面向 iOS 与 macOS 的代码图谱

Canonical source: https://maguyva.ai/zh-hans/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-hans/docs/quickstart)连接仓库，然后在[兼容性页面](/zh-hans/docs/compatibility)查看支持矩阵。如果同一产品也在 Android 上发布，请阅读 [Kotlin 指南](/zh-hans/languages/kotlin)。

## 引擎细节

- 可调用符号包括函数、`init`、`deinit`、下标、计算属性的 getter 和 setter，以及 `willSet` / `didSet` 观察器。
- 结构体、枚举、协议和扩展的成员会以所属类型限定，例如 `CartStore.add`。
- 定义名会去掉泛型参数、协议遵循列表以及 `?` / `!` 后缀，调用会保留 `self.` 和类限定。

## 常用 MCP 入口工具

- `find_symbol`: 需要定义和引用时，用类型、协议或方法名来查找。
- `dependency_search`: 对协议使用它，可找到遵循它的类型；对方法使用 incoming 方向，可找到调用方。
- `get_task_context`: 适用于“解释一条推送通知是如何到达收件箱界面的”这类提示词。