PyTorch 中的 Pyrefly 类型覆盖率迁移：从 SKILL 文档看文件级严格类型检查的完整落地流程

本篇围绕 PyTorch 仓库中的 .claude/skills/pyrefly-type-coverage/SKILL.md 展开，系统讲解将一个 Python 文件迁移到 Pyrefly 严格类型检查（所有函数、类、属性强制带注解）的七步标准流程：移除文件级抑制、配置 pyrefly.toml 子配置、运行检查并按规则分类处置错误、按"注解阶梯"补全注解、迭代修复、Lint 与测试验证。读完后你能够在 PyTorch 项目中独立完成一次类型覆盖率迁移，并理解其背后的仓库级证据：根目录 pyrefly.toml 的真实子配置写法、torch/fx/_compatibility.py 的后向兼容装饰器实现，以及 test/test_fx.py 中基于 golden 文件的签名锁定测试。

Pyrefly 在 PyTorch 中的定位：全局宽松、局部收紧

PyTorch 仓库根目录维护了一份 pyrefly.toml，文件头部注释说明其配置"Based on mypy.ini"，即从原 mypy 体系平滑迁移而来。它的顶层策略是全局相对宽松：

• python-version = "3.12"；
• untyped-def-behavior = "check-and-infer-return-any"：对无注解函数体仍做检查，但返回值推断为 Any；
• 全局关闭了一批历史包袱类报错：implicitly-defined-attribute、bad-param-name-override、implicit-import、deprecated 均为 false，理由是"大量属性在 __init__ 中定义""很多覆写方法会重命名参数""mypy 也不强制显式 import"；
• project-includes / project-excludes 精细圈定检查范围（torch、caffe2、tools 及若干 test/*.py，排除 notebook、vendored 代码等）。

在此基础上，仓库通过大量 [[sub-config]] 块对特定目录或单文件逐步收紧。当前 pyrefly.toml 中已存在多个真实示例，例如 torch/_dynamo/**、torch/_dispatch/**、torch/_functorch/** 开启了 implicit-any = true；而 torch/fx/** 与 torch/optim/optimizer.py 等条目已经完整开启：

[[sub-config]]
matches = "torch/fx/**"
[sub-config.errors]
implicit-import = false
implicit-any = true
bad-param-name-override = false
unannotated-return = true
unannotated-parameter = true
unannotated-attribute = true

这正是 SKILL 文档所描述的迁移目标形态：一个文件的"类型覆盖"提升，本质上就是在 pyrefly.toml 中新增一个子配置，然后让该文件通过检查。以下流程全部继承自 SKILL.md。

前置条件

迁移开始前必须确认：

1. 目标文件位于一个拥有 pyrefly.toml 的项目中（PyTorch 即满足）；
2. pyrefly、lintrunner 与项目的测试运行器都在 PATH 上。

若其中任何一个缺失，应停下来询问是否需要激活 conda 环境，而不是自行安装或用其他工具替代（这一约束来自仓库的 CLAUDE.md 约定）。

Step 1：移除文件级类型检查抑制

先删除目标文件头部的所有文件级抑制注释。Pyrefly 出于 mypy 兼容会识别 # mypy: ignore-errors，所以这一行也必须一并删除。SKILL 文档明确列出了四种需要清理的写法：

# pyre-ignore-all-errors
# pyre-ignore-all-errors[16,21,53,56]
# @lint-ignore-every PYRELINT
# mypy: ignore-errors

Step 2：在 pyrefly.toml 中新增子配置条目

为目标文件所在的目录（或文件）追加一个子配置，SKILL 文档给出的模板是：

[[sub-config]]
matches = "path/to/directory/**"
[sub-config.errors]
implicit-import = false
implicit-any = true
bad-param-name-override = false
unannotated-return = true
unannotated-parameter = true

其中 implicit-import = false 与 bad-param-name-override = false 是刻意"镜像"全局配置的（全局本来就关了这两项），目的是防止报错语义漂移；真正新增的严格项是 implicit-any、unannotated-return、unannotated-parameter 三项——这就是本流程的三个"目标类目"。

关键注意事项：子配置中设置任何一个 error 键，都只相对于父配置覆盖该键本身；但开启 unannotated-return / unannotated-parameter / implicit-any 会把此前被文件级抑制注释掩盖的旧错误一并"复活"。如果此时看到无关错误（例如 bad-param-name-override）刷屏，正确做法是在子配置里把该键按父配置的取值镜像一份以压住噪声，而不是去改文件里的代码。

Step 3：运行 pyrefly 并按"报告位置"分类处置错误

pyrefly check <FILENAME>

目标是解决所有 unannotated-return、unannotated-parameter、implicit-any 错误——方式只有补注解，这三个目标类目永远可以解决，绝不允许用 # pyrefly: ignore 压掉（唯一例外是下文"后向兼容豁免"）。

其余类目（bad-argument-type、missing-attribute 等）属于真实类型缺陷，处置原则是看 pyrefly 把错误报告在哪个文件：

• 报告在别的文件（路径 ≠ 目标文件）：不动它，不扩大改动范围。若该错误恰好阻塞了目标文件的检查，就在报告发生地用 # pyrefly: ignore[<category>] # TODO 压制；
• 报告在目标文件、但报错信息指向别处定义的符号（例如因某个导入函数注解有误而报 bad-return）：在本地用同样的 TODO 注释压制，不要伪造一个 cast() 去掩盖上游缺口；
• 报告在目标文件且错误根源就在本地：直接修复。

# pyrefly: ignore[...] 只能作为最后手段，且只能用于非目标类目。

Step 4：补全注解——约定与"注解阶梯"

当函数体看不出正确类型时，要回到调用点去确认。SKILL 文档给出了 PyTorch 项目内一整套注解约定：

基础语法与导入约定

• 使用 PEP 604 / PEP 585 语法（int | None、list[str]），假设 Python ≥ 3.10；
• 抽象类型优先用 collections.abc 而非 typing（Callable、Sequence、Generator 等）；
• 泛型辅助类型在项目最低 Python 版本可用时从 typing 导入，只有需要更新特性时才用 typing_extensions（如支持 <3.11/3.12 时的 Self、override，或 PEP 696 的 TypeVar / ParamSpec 的 default=）。不要无脑从 typing_extensions 导入；
• Callable 永远要参数化，禁止裸 Callable。优先 Callable[..., object]；只有当调用方真的消费了动态返回值时才用 Callable[..., Any]——如果结果只是被透传（甚至这个 callable 根本没被调用），object 更严格且同样正确；
• 新建的模块级全局名一律加前导下划线：TypeVar/ParamSpec（与字符串参数一致：_T = TypeVar("_T")、_P = ParamSpec("_P")、_R = TypeVar("_R")）、TypeAlias、辅助常量、哨兵值皆如此。这是 torch 对非公开名的主流约定（据 SKILL 文档统计，代码树中 _P 出现次数约为 P 的 6 倍）。例外：被其他模块导入的名字、列入 __all__ 的名字、或作为运行时 token 的名字（如注解字符串派发标记）保持无下划线。只约束你新增的名字，不要顺手重命名既有全局变量——那属于本次技能范围之外的无关重构。

一个现成的仓库内印证是 torch/fx/_compatibility.py：其中 _T = TypeVar("_T")、_BACK_COMPAT_OBJECTS: dict[Any, None] = {} 均为下划线前缀的非公开名，且 compatibility() 返回 Callable[[_T], _T]，恰好是"透传类型"用 TypeVar 而非 Any 的范例。

谓函数与类型收窄

• 布尔谓函数——is_*/has_* 命名、接收宽类型（常见 object）、返回 bool——通常应标注 TypeGuard[X]（或 TypeIs[X]，后者还能收窄否定分支）。TypeGuard 自 3.10 起在 typing 中，直接从 typing 导入；TypeIs 直到 3.13 才进入 typing，因此为保持 3.10 兼容应从 typing_extensions（≥4.10）导入；
• 接收 klass: type[_T] 的 issubclass 风格辅助函数应返回 TypeGuard[type[_T]]；优先用显式的 isinstance(x, type) 守卫，而不是在 issubclass() 外包 try/except TypeError——前者更清晰，也能让检查器收窄。

TypeVar：何时用、何时不该用

当返回值派生自参数时——透传/恒等函数、"返回这些参数之一"的辅助函数、装饰器、按类型做键的注册表——应使用 TypeVar（若签名需透传的是 callable 参数，则用 ParamSpec/TypeVar 组合成 Callable[_P, _R]），而不是放宽到 object/Any。"输出类型 == 某个输入类型"正是 TypeVar 所编码的语义；object in / object out 会把信息丢掉。注意反向情形：如果函数变换了值、输出类型与输入不同（比如把数组转成 int），单个 TypeVar 就是错的——应直接命名真实的领域类型。

其他结构性约定：

• 在 __init__ 中赋值的类属性，应在类级别补注解，让 pyrefly 能看到；
• 用 if TYPE_CHECKING: 打破 import 环——仅注解用的导入放进守卫，并配合 from __future__ import annotations（或字符串前向引用）保持运行时惰性导入：

from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from torch.fx import GraphModule
def transform(gm: GraphModule) -> GraphModule: ...

"放宽而不是放弃"：四级注解阶梯

当正确类型难以推断时，按下面阶梯逐级下探，而不是直接 ignore：

1. 从调用点与返回路径可观察到的最具体具体类型；
2. 联合类型（X | Y）、Sequence[X] 式抽象类型，或对真正泛型函数（恒等透传、容器辅助）使用带约束的 TypeVar；
3. object —— 仍能通过类型检查的最严格兜底，迫使调用方先收窄再使用，例如 def serialize(value: object) -> str:。它外观上与 Any 相似但更严格——不加 isinstance 时 pyrefly 会拒绝 value.foo()；
4. Any —— 最后一级。永远优先于对目标类目的 # pyrefly: ignore，但仅在第 1–3 级都失败后才可用，且你能说清楚每一级为何不适用（例如"联合类型超过 8 种""观察不到公共上界""调用方确实从不收窄"）。

配套的两条纪律：

• 特别警惕返回值位置的 object/Any——函数通常比调用方更清楚自己产出了什么。宽返回只在真正的边界处正确（原样返回输入，或值由 handler/调用方决定）；若函数体构造了已知形状，就命名它（领域别名或联合优于 object）；
• 判定某参数必须是 Any 之前，至少读三个调用点——不要凭第一眼"看起来动态"就下结论。

# pyrefly: ignore[...] 的窄范围用法（非目标类目）保留给 pyrefly 确实错了的具体局部错误——动态元编程、第三方 stub 缺口：

# pyrefly: ignore[attr-defined]
result = getattr(obj, dynamic_name)()

若行内 ignore 注释会让该行超出行宽限制，把它放在被标记行的上一行（pyrefly 支持上一行的 ignore），而不是为了保留行内注释去加 # fmt: skip——唯一的例外是后向兼容豁免，那里注释必须写在 def 行上。

后向兼容豁免：唯一允许压制目标类目的场景

关键规则：被 @compatibility(is_backward_compatible=True) 装饰的函数，签名不得改动。后向兼容测试 test_function_back_compat 会把 inspect.signature 的字符串化结果与 golden 文件比对——哪怕只加 -> None 这样的注解，字符串都会变化，测试即失败。此时应改用 pyrefly ignore 注释：

@compatibility(is_backward_compatible=True)
def my_function(  # pyrefly: ignore[unannotated-return]
    self,
    arg1,  # can't add type here either
):
    ...

# pyrefly: ignore 注释必须位于 def 行（pyrefly 报错的位置），而不是收尾的 ) 上。

这套机制在仓库中有完整闭环。装饰器定义在 torch/fx/_compatibility.py：compatibility(is_backward_compatible=True) 会给函数 docstring 追加"Backwards-compatibility for this API is guaranteed"说明，并把对象注册进 _BACK_COMPAT_OBJECTS。消费端在 test/test_fx.py 的 test_function_back_compat 中：它遍历 _BACK_COMPAT_OBJECTS，用 _fn_to_stable_annotation_str 手工序列化签名（注释说明这是因为 inspect.Signature 的序列化在不同 Python 版本间不稳定，且要避免把模块路径、函数内存地址写进 golden 文件），与 golden 文件 fx_backcompat_function_signatures 比对；不一致时错误信息会明确提示"如属有意变更，请与 FX 团队确认弃用流程后 --accept"。

ParamSpec：保签名包装器

装饰器、functools.wraps 风格的辅助函数应使用 Callable[P, R]，让被包装函数的签名流向调用方——Callable[..., Any] 会丢失这一信息；只有当包装器真的接受任意 callable 时才跳过 ParamSpec。包装器在前/后追加参数时，与 Concatenate[X, P] 搭配使用：

from collections.abc import Callable
from typing import ParamSpec, TypeVar

_P = ParamSpec("_P")
_R = TypeVar("_R")

def log_calls(fn: Callable[_P, _R]) -> Callable[_P, _R]:
    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
        return fn(*args, **kwargs)
    return wrapper

Step 5：迭代直至干净

重跑 pyrefly check。新注解往往会暴露 bad-return——即函数实际返回了不兼容类型，逐一修复，循环到零错误。

还有一个容易遗漏的收尾动作：收紧共享辅助函数（加 TypeGuard 或精确返回类型）后，其调用方中既有的 # pyrefly: ignore 可能已经失效。要回头检查并删除这些"僵尸抑制"及其配套的解释性注释——不留死代码。

Step 6：Lint（交付前必做）

注解常常会改变 import 顺序与行宽，因此在交接前必须跑：

lintrunner -a <files...>

lintrunner 无法自动修复的项要手工处理干净。

Step 7：测试与优先级规则

失败时的优先级：测试通过 > pyrefly 干净 > 注解严格度。如果新加的注解弄坏了测试，先按阶梯把注解降一级（如具体类型 → object，或撤销破坏下游 isinstance 检查的 Any 放宽），再考虑回退整个文件。

1. 后向兼容检查。仅当目标文件命中下述 grep 时才需要跑——@compatibility(is_backward_compatible=True) 装饰器才是 golden 文件比对的真正前置条件；"import 了 torch.fx"这一更宽的启发式会误中 torch/ 里约一半的文件，不可作为依据：

   grep -l '@compatibility(is_backward_compatible=True)' <target>
   python -m pytest test/test_fx.py::TestFXAPIBackwardCompatibility -x -v
   

2. 修改模块的单元测试。下结论"没有覆盖"之前，两个方向都要搜：

   # torch/foo/bar.py 通常由 test/test_foo.py 或 test/test_bar.py 覆盖
   ls test/ | grep -i <module-name>
   # 或者按 import 关系找
   grep -rl "from torch.foo.bar import\|import torch.foo.bar" test/
   

   两者都为空时要明确告知用户，不要静默跳过。类型变更可能引入真实的运行时回归（例如 .append 被调用时 Optional[X] vs X、Sequence vs list 的差异）。

收尾注意事项

• 类体中的前向引用：即使没有 from __future__ import annotations，某些位置仍需字符串引号：

  class MyClass:
      def __new__(cls) -> "MyClass": ...
  

• 提交纪律：除非用户明确要求，不提交（per repo CLAUDE.md）。文件检查干净后停下来，把 diff 呈现给用户评审。

小结

这篇技能文档把"给一个文件上严格类型检查"压缩成了一条可复现的流水线：清抑制 → 加子配置 → 按错误报告位置分类处置 → 沿注解阶梯补全（object 优于 Any，TypeVar 优于放宽）→ 迭代清理僵尸 ignore → lintrunner → 测试验证，并用"测试通过 > 检查干净 > 注解严格"的优先级保证迁移不引入行为回归。它与 pyrefly.toml 中逐目录收紧的子配置策略、torch/fx/_compatibility.py 的签名锁定机制、test/test_fx.py 的 TestFXAPIBackwardCompatibility 共同构成了 PyTorch 类型覆盖率逐步提升的完整工程闭环。