Pyrefly v1.0 正式发布

# Pyrefly v1.0 正式发布！ 来源：https://pyrefly.org/blog/v1.0/ Pyrefly v1.0 今天我们很高兴地宣布，Pyrefly——我们的开源 Python 类型检查器和语言服务器——已正式达到稳定版 1.0 状态。这意味着我们有信心 Pyrefly 已准备好用于生产环境。 Pyrefly 是一个 Python 代码分析工具，可帮助你在代码中查找 bug，为你的 AI 智能体提供结构支持，并让你在 IDE 中获得更快的导航体验。它最初于 2025 年中以 Alpha 版本发布，随后在同年 11 月推出了 Beta 版。自那以后，我们已经发布了 60 多个小版本：修复了数百个 bug，增加了你一直要求的功能，并将性能提升到了同类工具中的领先水平。 在继续之前，我们必须感谢我们出色的开源社区！感谢所有在 GitHub 上提交 issue、提交 pull request、在大会上给予我们反馈、或加入我们 Discord 的朋友们：谢谢你们。你们的贡献塑造了这次发布，我们对每一个贡献都心怀感激，并希望你们继续参与未来版本的旅程。 那么 V1 对你来说究竟意味着什么？在这篇文章中，我们将回顾自 Beta 版以来的变化、Pyrefly 现在能为你的代码库做些什么，以及我们下一步的计划。 ## Pyrefly 已为生产就绪 (https://pyrefly.org/blog/v1.0/#pyrefly-is-production-ready) 我们经常被问到的一个问题是：“Pyrefly 什么时候可以用于生产环境？” 即使在正式提升版本号之前，Pyrefly 就已经是 Meta 旗下 Instagram 开发者的默认类型检查器。它也被其他大型生产代码库所采用，比如 PyTorch、NumPy、Pandas（存根）和 JAX，这些项目对稳定性和性能的要求是不容妥协的。而在撰写本文时，Pyrefly IDE 扩展也是 Open VSX 注册表 (https://open-vsx.org/) 上下载量最高的扩展。 正如语义化版本 FAQ (https://semver.org/?fbclid=IwY2xjawRe-aNleHRuA2FlbQIxMQBicmlkETFLUmZRckx3Zzl3ajlLd2Nhc3J0YwZhcHBfaWQBMAABHtUjUIlkI7F5LvTx9z-G8a0FaHUYI3WP579AlNhT5N9Q52fcra425xSCahjN_aem_ffD9QDOiZ-o9gx7QI-p4qA#how-do-i-know-when-to-release-100) 所述：“如果你的软件已在生产环境中使用，那么它可能早该是 1.0.0 了。” 所以我们认为现在是时候正式宣布了。 ## 更快、更准确、更可靠 (https://pyrefly.org/blog/v1.0/#faster-more-accurate-more-reliable) 从一开始，我们的策略就是让 Pyrefly 广泛覆盖 Python 类型规范与语言语义，即使早期版本可能会比用户预期的报出更多错误。我们相信从全面起步再逐渐精炼要好于从狭窄起步并随着时间推移用新错误让用户感到意外。因此，如果你早期尝试过 Pyrefly 并觉得它过于嘈杂，那么现在是时候重新审视了。得益于你持续的反馈，我们已经修复了数百个 bug，并在性能问题出现时迅速解决，使得每个新发布的 Pyrefly 都比上一个版本更高效。 在性能方面，我们专注于让 Pyrefly 在大型代码库上更快、更轻量。自 Beta 版本以来，PyTorch 的完整类型检查速度提升了 34%，而增量编辑器更新则最多可以快 125 倍。具体来说，在一次编辑之后，Pyrefly 现在在 19 毫秒内更新 PyTorch 的诊断信息，而之前是 2.4 秒¹ (https://pyrefly.org/blog/v1.0/#user-content-fn-1-73e829)。我们还投入了精力减少误报，从而使你的编辑器更安静，而你所看到的错误都是值得处理的。 为了确保我们持续改进，我们构建了一个开放基准测试套件 (https://python-type-checking.com/typecheck_benchmark/)，每天针对 53 个流行的开源 Python 包运行。它追踪 Pyrefly 和其他流行类型检查器的执行时间与峰值内存使用，让我们能够尽早发现回归，并向社区透明地分享进展。 ## 适用于真实世界的 Python 代码库 (https://pyrefly.org/blog/v1.0/#works-with-real-world-python-codebases) Python 项目没有完全相同的。你或许在用 Antigravity 进行“氛围编码”原型、在 CI 中对庞大代码库运行类型检查，或者使用 Pydantic 和 Django 构建生产级 API。在迈向 1.0 版本的过程中，我们一直专注于让 Pyrefly 适应现代 Python 开发者所需的各种配置。 现有类型检查器的一个常见问题是，你的编辑器和 CI 可能给出不同的结果。Pyrefly 通过同时提供 CLI 工具和 IDE 扩展避免了这一问题，让你在所有地方都能获得一致的结果。在过去一年中，我们也看到越来越多的编辑器采用了 Pyrefly，包括新的 AI 前沿 IDE，它们要么通过专用扩展 (https://www.youtube.com/shorts/GxzJu0NrUP0) 加入，要么将 Pyrefly 设为其默认语言服务器 (https://positron.posit.co/blog/posts/2026-03-31-python-type-checkers/)。目前，我们正激动地与微软合作，通过新的类型服务器协议 (TSP) 将 Pyrefly 支持引入 Pylance。该集成目前已在 VSCode Insiders 版本中早期预览，允许用户选择 Pyrefly 进行类型检查，同时保留 Pylance 的功能（例如与 GitHub Copilot 的集成）。 Pyrefly 现在还对 Pydantic 和 Django 提供了内置支持，包括模型验证、字段类型和模型字段的自动补全。自首次发布 (https://pyrefly.org/blog/pyrefly-beta/#preliminary-support-for-pydantic-and-django) 以来，我们一直在稳步改进这些支持，并将继续根据你的反馈进行优化。 ## 按自己的节奏采用 (https://pyrefly.org/blog/v1.0/#adopt-at-your-own-pace) 无论你是经验丰富的类型检查器用户，还是刚开始为代码库添加类型，Pyrefly 都能与你当前的阶段相匹配。 如果你准备开始使用最新版本的 Pyrefly，可以快速安装命令行工具： 或者从安装页面 (https://pyrefly.org/en/docs/installation/) 获取适合你编辑器的 IDE 扩展。你也可以在安装任何东西之前通过我们的在线沙箱 (https://pyrefly.org/en/sandbox/) 在浏览器中试用 Pyrefly。 如果你是首次安装 Pyrefly 且没有现有的类型检查器配置，它默认使用 **basic 预设**。该预设只显示高置信度的错误，比如语法错误和缺失的导入，这些错误很可能意味着真正的 bug 或崩溃。其他诊断会被静默。你可以通过 VSCode 设置调整类型检查模式，或运行 `pyrefly init` 创建配置文件（`pyproject.toml`、`pyrefly.toml`）。请查看配置文档 (https://pyrefly.org/en/docs/configuration/#preset) 了解预设详情和其他选项。 ### 从其他类型检查器迁移 (https://pyrefly.org/blog/v1.0/#migrating-from-another-type-checker) 如果你已经在使用 Mypy 或 Pyright，安装 Pyrefly 时它会读取你现有的配置并尽力匹配，因此你不必从头开始配置所有内容。但这不会永久保存你的 Pyrefly 配置，因此我们建议运行 `pyrefly init` 来自动创建 `pyrefly.toml`（或更新 `pyproject.toml`）并保存这些设置。 ### 增量式添加 Pyrefly (https://pyrefly.org/blog/v1.0/#add-pyrefly-incrementally) 你无需在第一天就对整个代码库进行类型检查。在 `pyrefly.toml` 或 `pyproject.toml` 中使用 `project_excludes` 来排除代码库中的特定区域，只对新增代码运行 Pyrefly，然后逐步将遗留模块纳入检查范围。 ``` project_excludes=['src/my/legacy/code'] ``` ### 逐步采用类型 (https://pyrefly.org/blog/v1.0/#gradually-adopting-types) 如果你的代码库几乎没有类型覆盖，Pyrefly 可以从你现有的阶段开始。尝试先从一两个文件开始，然后逐步扩展类型覆盖范围。 当你准备显式添加注解时，`pyrefly infer` 可以帮助完成繁重的工作。在命令行运行它以生成草稿类型的注解。例如，它可以将： ``` def total(numbers): result = [] for n in numbers: result.append(n * 2) return sum(result) ``` 转换为： ``` def total(numbers: list[int]) -> int: result = [] for n in numbers: result.append(n * 2) return sum(result) ``` 根据代码的编写方式，有时可能难以正确推断类型，因此我们建议在合并前检查输出。 一旦开始添加类型，`pyrefly report` 可以帮助你追踪进度。它会生成关于整个代码库注解完整性和类型完整性的摘要，让你了解当前状态并设定改进目标。 ## 下一步：面向 AI 原生时代的 Pyrefly (https://pyrefly.org/blog/v1.0/#whats-next-pyrefly-for-the-ai-native-era) V1 是一个重要的里程碑，但还有更多事情要做！未来我们将继续做我们正在做的事情：扩展对第三方库的支持，并减少大量的长尾误报。同时，我们也在积极倾听社区关于可用性的反馈，并根据您的意见持续迭代。此外，我们还有一些新的全新计划，对此我们非常兴奋。 ### 张量形状检查 (https://pyrefly.org/blog/v1.0/#tensor-shape-checking) 我们特别感兴趣的一个实验性功能是 PyTorch 和其他机器学习框架的张量形状检查。形状不匹配是机器学习代码中最令人沮丧的运行时错误来源之一，而且当它们在训练运行数小时后崩溃时，发现它们的代价会很高。 Pyrefly 的实验性张量形状支持允许你向模型添加一种包含形状信息的新形式的类型注解，这样类型检查器可以跟踪张量维度在代码中的流动，并在静态时捕获不匹配。以下是一个类型化的 PyTorch 模型的简单示例： ```python import torch.nn as nn from torch import Tensor from torch_shapes import Dim # 来自 pyrefly 的新类型注解扩展 class BaselineActor[S, A](nn.Module): def __init__(self, state_size: Dim[S], action_size: Dim[A]) -> None: super().__init__() self.fc1 = nn.Linear(state_size, 400) self.fc2 = nn.Linear(400, 400) self.out = nn.Linear(400, action_size) def forward[B](self, state: Tensor[B, S]) -> Tensor[B, A]: h1 = F.relu(self.fc1(state)) # Pyrefly 推断：Tensor[B, 400] h2 = F.relu(self.fc2(h1)) # Pyrefly 推断：Tensor[B, 400] return torch.tanh(self.out(h2)) # Pyrefly 推断：Tensor[B, A] ``` 只需在类和函数边界添加少量注解，Pyrefly 就能推断出所有中间张量的形状，并在编辑器中以内嵌提示的形式显示。如果引入了形状不匹配（例如连接了两个维度不兼容的层），Pyrefly 会在你运行代码之前就捕捉到它。 这一功能仍处于实验阶段，我们希望积极与 Python 类型社区互动，共同改进并将其推向更远。你可以查看此处的文档 (https://pyrefly.org/en/docs/tensor-shapes/) 获取更多信息。 ### 为你和你的 AI 助手提供快速反馈循环 (https://pyrefly.org/blog/v1.0/#a-fast-feedback-loop-for-you-and-your-ai-assistant) 不断增长的代码库始终受益于静态类型的“安全网”，而在当今 AI 辅助代码量激增的背景下，这一点比以往任何时候都更加重要。Pyrefly 的速度使其自然适合作为智能体工作流中的验证步骤，因此我们正在研究不同的方法，让您在利用 Pyrefly 配合 AI 智能体时更加轻松。 我们已经发布了一份关于将 Pyrefly 添加到你的智能体循环 (https://pyrefly.org/blog/pyrefly-agentic-loop/) 的指南，其中介绍了两种方法。但 AI 工具领域的演变非常迅速。如何最好地将类型检查集成到智能体工作流中仍然是一个移动的目标，结果会因你的设置和模型而异。这是我们正在积极研究的领域，我们将在了解更多信息后不断更新文档和博客。我们也非常想听听你是如何将 Pyrefly 与自己智能体配合使用的。 ## 结论 (https://pyrefly.org/blog/v1.0/#conclusion) 一年前我们发布 Alpha 版本 (https://pyrefly.org/blog/introducing-pyrefly/) 时，曾说过我们希望构建一个类型检查器：性能卓越、IDE 体验良好、类型推断令人印象深刻，并且是真正的开源协作。感谢所有忠实的用户和贡献者，我们有信心已经实现了这些目标，并将通过每一次发布继续提高标准。 我们才刚刚开始，无论你是一路相伴还是今天才首次了解 Pyrefly，我们都希望你能成为未来的一部分。在 GitHub (https://github.com/facebook/pyrefly) 和 Discord (https://discord.gg/Cf7mFQtW7W) 上找到我们，继续讨论。 --- 1. 在 M4 MacBook Pro 上测试 ↩ (https://pyrefly.org/blog/v1.0/#user-content-fnref-1-73e829)