# Maguyva 对 Python 的支持：AI 代码搜索与重构

Canonical source: https://maguyva.ai/zh-hans/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 服务的团队。
- 在修改某个处理器、服务、模型或辅助函数之前，需要不止于 grep 的智能体工作流。

## 智能体工作流

- 在修改之前，追踪某个端点、任务或命令行命令如何流经辅助函数和共享模块。
- 找出某个服务、类或工具函数在代码仓库中被实例化和复用的位置。
- 对比相邻实现，确保智能体修改的是正确的抽象，而不是文本最接近的那一处。

## Python 代码仓库通常在哪里让肤浅的 AI 工具露出马脚

Python 正是许多 AI 编码工具乍看不错、一到生产环境就开始瞎猜的地方。那些难点都很眼熟：被装饰器包裹的入口点、服务类、类型存根、遍地都是的小型辅助模块，以及只有把 `self` 或 `cls` 重新关联回它们所属的类之后才讲得通的方法。

对 Python 而言，真正的问题不是“它能不能读 `.py` 文件”，而是智能体能否在从端点走向服务、从后台任务走向辅助函数、或从类名走向真正实现该行为的方法时，始终保持有据可依。

## Maguyva 在 Python 中实际提取了什么

Maguyva 对 Python 提供完整的代码结构解析支持。该配置覆盖 `.py`、`.pyw` 和 `.pyi`；把 `decorated_definition` 映射回对应的函数符号；并将 `self` / `cls` 方法调用限定回其所属的类。这一点很重要，因为这些恰恰是 Python 代码仓库对人类来说显而易见、对 LLM 来说却模糊不清的地方。

它还从关系提取中过滤掉了大量标准库噪声。这意味着来自 `pathlib`、`typing` 或 `logging` 等模块的常见运行时调用，不太可能淹没你真正关心的、特定于代码仓库的关系。

## 面向 Python 代码仓库的实用 MCP 工作流

最简单实用的工作流是：

- 先用 `intelligent_search` 处理诸如“发票同步周边的重试逻辑”或“计费端点中的权限检查”这类行为层面的问题。
- 一旦你已知想关注的类名或函数名，就切换到 `find_symbol`。
- 在重构某个共享服务、辅助函数或基类之前，用带入向遍历的 `dependency_search`。

这种模式，比在毫无上下文的情况下就让智能体“更新计费流程”要好得多。它让智能体先建立地图，再动手改代码。

## 这个页面何时有用

这个页面适用于已经有一定年头和复杂度的 Python 代码仓库：服务代码、任务、脚本、生成的类型，以及周边配置。如果你主要是在多语言 Web Monorepo 之间做对比，也可以读一读 [TypeScript 指南](/zh-hans/languages/typescript)。如果你只需要完整的支持矩阵，请查看 [兼容性](/zh-hans/docs/compatibility)。

## 引擎细节

- 带装饰器的定义仍被视为函数，因此带装饰器的视图和任务依然可作为符号被搜索到。
- `self` 和 `cls` 方法调用会被限定回所属类，这有助于图谱在类密集的服务代码中保持可用性。
- 导入、调用和符号归一化器均已启用，同时 `pathlib.*`、`typing.*`、`logging.*` 等常见标准库噪声会从关系中被过滤掉。

## 常用 MCP 入口工具

- `intelligent_search`: 从一个概念性查询开始，例如“发票同步相关的重试逻辑”；如果仓库是多语言的，可设置 `language_filter="python"`。
- `find_symbol`: 当你已知类名或函数名，需要在编辑前拿到定义和引用时使用。
- `dependency_search`: 在重构共享服务或辅助函数前，先沿入向关系查看哪些代码依赖它。