Pyrefly：PyTorch 团队出品的 Python 严格类型迁移神器

写 Python 这么多年，你有没有这种感觉——类型注解加着加着就乱了？mypy: ignore-all-errors 满天飞，Any 当万能解，函数签名改着改着就不知道原来长什么样了。

PyTorch 团队内部其实早有一套解决方案，叫 Pyrefly——一个专为大型 Python 代码库设计的严格类型检查工具。最近官方把它做成 Claude Skill，直接扔给 AI 执行，帮你把「乱糟糟的 Python 文件」迁移成「严格类型安全」的生产级代码。

这 Skill 到底干什么

简单说：给定一个 Python 文件，它会一步步带你完成类型注解的全面升级。

核心逻辑分七步：

• 去掉 suppressions——先把文件头那些 # pyrefly-ignore-all-errors 删干净
• 配 sub-config——在 pyrefly.toml 里给目标目录单独配置，开启 unannotated-return / unannotated-parameter / implicit-any 三个强制检查
• 跑 pyrefly check——盯着那三个目标错误类别，逐一解决，永远不 suppress 它们
• 加注解——优先用 PEP 604 语法（int | None），用 collections.abc 代替 typing，永远 parameterize Callable
• 迭代——重复 check，修掉新暴露的 bad-return 错误
• Lint——lintrunner -a 过一遍，保证格式整洁
• 测试——跑单元测试，特别留意 @compatibility(is_backward_compatible=True) 装饰器的函数，不能改签名

注解 ladder：Any 是最后防线

最有价值的是它的「加注解优先级 ladder」：

1. 最具体的具体类型（联合类型、抽象类型）
2. object——严格版 Any，pyrefly 拒绝 value.foo() 隐式调用
3. Any——最后的逃生口，每次用都要能说出理由

这个 ladder 直接解决了「什么时候该用 Any」这个社区经典争议——答案是尽量不用，用了就得能讲清楚为什么前面几层都不适用。

Backward Compatibility 的唯一例外

Skill 里特别强调：被 @compatibility(is_backward_compatible=True) 装饰的函数，绝对不能改签名。测试用 inspect.signature 比对字符串，加个 -> None 都会导致 golden file 不匹配。这种函数用 # pyrefly: ignore[unannotated-return] 而非加注解。

适合谁用

• 正在维护 大型 Python 代码库的团队（PyTorch 官方出品，质量有保证）
• 想让 AI 助手帮自己系统性提升代码类型安全度的开发者
• 对 mypy 基础薄弱、想学习「正确做类型迁移」路径的工程师

这个 Skill 安装量目前只有 21（Smithery 上），属于非常垂直的专业工具——但正因为垂直，它把「怎么做」说得极细，PyTorch 团队踩过的坑全在里面了。

如果你也在跟 PyTorch 一样的大型 Python 项目搏斗，或者想让 Claude 帮你做一次彻底的类型安全升级，这个 Skill 值得直接装上试试。

GitHub 仓库 →

GitHub: https://github.com/pytorch/pytorch/tree/main/.claude/skills/pyrefly-type-coverage