# Maguyva 的 Perl 支持：包与子程序图谱

Canonical source: https://maguyva.ai/zh-hans/languages/perl

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、符号和图谱支持 Perl，让 AI 智能体在遗留 Perl 中追踪包、子程序、use 和 require 导入以及构造器。

## 支持情况速览

- 支持等级: AST 和符号支持
- 编程语言
- 扩展名: .perl, .pl, .pm, .pod, .t
- 真正的 AST 解析，支撑语法感知搜索和结构化上下文。
- 命名符号支撑语义查找和交叉引用。启用关系提取后，即可使用图谱导航。
- 该语言为图谱感知搜索提供符号和关系；支持的边类型随其原生构造而异。
- 同时支持 AST 解析和符号提取。

## 最适合场景

- 接手了仍在生产环境运行的 Perl 服务、CGI 应用或批处理与报表脚本的团队。
- 以模块为主的代码库，`.pm` 包被大量脚本和测试文件共享。
- 迁移或下线工作，首先要回答的是哪些脚本依赖哪些模块。

## 智能体工作流

- 在修改共享包之前，列出所有使用它的脚本和模块。
- 找出某个类在哪里通过 `->new` 构造，以及接下来调用了哪些子程序。
- 从入口脚本出发，沿着加载的模块追踪一个报表或作业。

## 为什么 Perl 资产很难安全地修改

Perl 代码紧凑、灵活，而且往往出自多年前就已离开的人之手。sigil 会改变名称的含义，包同时充当类，同一个模块会被许多目录下的脚本加载。文本搜索能找到字符串，却不能告诉智能体一个脚本实际调用的是哪个子程序。

Maguyva 把包、子程序、导入和构造器作为结构交给智能体，让它在动代码之前先划定修改的范围。

## Maguyva 在 Perl 中提取什么

Maguyva 覆盖 `.pl`、`.pm`、`.t`、`.pod` 和 `.perl`。子程序被提取为函数，`package` 声明被提取为类，定义名中的 sigil（`$`、`@`、`%`、`&`、`*`）会被去掉，因此变量和子程序都可以按裸名称搜索。

导入来自 `use`、`require` 和 `package` 语句。`Class->new` 形式的方法调用计为实例化，`bless` 和 `tie` 被特意保留在调用图中。图谱还记录继承、重写、类型引用、读写以及异常抛出。

约 189 个内置函数（`print`、`open`、`die`、`warn` 等）会从调用关系中过滤掉，让仓库自身的代码更加突出。

## 智能体提示词示例

- “哪些脚本使用了 `Billing::Invoice`，它们调用了其中哪些子程序？”（`dependency_search` 的 incoming 方向）
- “`Report::Monthly` 在哪里被构造，`->new` 之后发生了什么？”（先用 `find_symbol`，再用 `get_task_context`）
- “找出所有测试 `Auth::Session` 的测试文件。”（先用 `text_pattern_search`，再用 `find_symbol`）

## 已知限制

- 传统的 Perl 方法就是包内普通的 `sub` 声明，因此在结构搜索中只有较新的专用 `method` 语法会被归类为方法。对于较早的面向对象 Perl，请使用 `functions` 预设。
- 对已过滤内置函数的调用不会作为图谱的边出现。需要找出每一个 `open` 或 `print` 调用时，请使用 `text_pattern_search`。

## 后续步骤

通过[快速入门](/zh-hans/docs/quickstart)连接仓库，然后在[兼容性页面](/zh-hans/docs/compatibility)查看支持矩阵。如果这些资产正在迁移到另一种脚本语言，请对照阅读 [Python 指南](/zh-hans/languages/python)。

## 引擎细节

- Perl 支持覆盖 `.pl`、`.pm`、`.t`、`.pod` 和 `.perl`。子程序是函数，`package` 声明是类。
- 定义名会去掉 sigil，`use` 和 `require` 会成为导入，`Class->new` 计为实例化。
- 约 189 个内置函数（如 `print`、`open` 和 `die`）会从调用中过滤掉，而 `bless` 和 `tie` 保留在图谱中。

## 常用 MCP 入口工具

- `find_symbol`: 用包名或子程序名查找；sigil 会被去掉，所以请按裸名称搜索。
- `dependency_search`: 对共享模块使用 incoming 遍历，查看哪些脚本和包依赖它。
- `text_pattern_search`: 用于查找调用图之外的已过滤内置函数、配置键和 SQL 字符串。