pyrefly-type-coverage：把单个文件从”类型宽松”推到”全注解”的手术刀

类型注解这事，大部分人的第一反应是”能跑就行”。但 PyTorch 这种千万行级别的仓库，早把类型检查从可选项变成了准入线。Meta 开源 Pyrefly 之后，PyTorch 是最早切过去的那批大仓库之一。

切过去容易，把存量代码逐文件补齐注解才是真正的苦活。Smithery 上这个 pytorch/pyrefly-type-coverage，就是官方把这件苦活写成的一份操作手册。它不做整仓迁移，只做一件事：把一个文件，从宽松检查推到所有函数、类、属性都必须有注解的严格档位。

我一开始以为这就是个”给函数加返回类型”的速查表。读完 SKILL.md 才发现，真正的功夫不在注解语法，而在那套”什么能 suppress、什么绝不能 suppress”的纪律。PEP 604 的语法谁都会写，边界判断才是这个技能值钱的地方。

这份文档的作者标识是 pytorch 组织，跟 docstring 那个技能一样，是从 PyTorch 真实代码库的贡献流程里沉淀出来的，不是社区个人随手写的。里面每一条规则，背后都对应一个真实踩过的坑。

工作流拆解

整个技能是一条七步流程，目标单一：让一个文件在 pyrefly 严格模式下通过检查。第一步是删掉文件顶部的检查抑制，# pyre-ignore-all-errors、# mypy: ignore-errors 这些历史遗留。不删掉它们，后面加的注解等于白加，因为整文件的错误都被屏蔽了。

第二步是在 pyrefly.toml 里给这个文件所在的目录加一个 sub-config 条目，把 implicit-any、unannotated-return、unannotated-parameter 这三个错误开关打开：

[[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

这里有个容易被忽略的坑。sub-config 只覆盖你显式写的 key，一旦打开这三个，之前被父配置压住的无关错误会一起冒出来。技能特意提醒：看到 bad-param-name-override 这类无关错误刷屏，就把父配置里对应的 key 镜像过来压回去。

第三步跑 pyrefly check <文件名>，然后才是重头戏：给报错的函数加注解。注解怎么写对，这条线是整个技能篇幅最重的地方，我放到下一节单独拆。这里先记住流程本身：加完注解不是完事，要回到第五步迭代。

迭代这一步才是真正在修 bug。新注解经常连锁出 bad-return 这种真实类型错误，说明函数实际返回的东西跟声明不符。补格式不会暴露这个问题，只有把注解加到位，隐藏的类型不一致才会浮出来。

最后两步是 lint 和测试。lint 是因为加注解会打乱 import 顺序和行宽；测试是因为类型收紧会引入真实的运行时回归。技能里有一条优先级写得很硬：

测试通过 > pyrefly 干净 > 注解严格

注解加得太激进导致测试挂掉，就退一档，别硬刚。

关键设计

这个技能最硬的一条规则，是那三个目标错误类别绝不能 suppress。unannotated-return、unannotated-parameter、implicit-any，这三个永远能靠加注解解决，# pyrefly: ignore 不是可接受的结局。

这条规则一开始看着像洁癖，其实是在防一个滑坡。一旦允许对目标类别用 ignore，整份技能就退化成”加 ignore 注释大赛”，跟它”把文件推到全注解”的初衷彻底相悖。

那类型实在推不出来怎么办？技能给了一条放宽阶梯，而不是让你投降：先从调用点和返回路径观察最具体的类型，推不出就上联合类型或 bound TypeVar，再不行落到 object，最后才是 Any。object 和 Any 看着像，实际是两回事。

object 是最严格的兜底，调用方必须 isinstance 收窄才能用；Any 是最后一档，等于关掉了检查。技能特别提醒，return 位置要警惕 object 和 Any，因为函数通常比调用方更清楚自己产出什么。这条把”怎么加注解”从语法问题变成了判断问题，是我读下来印象最深的地方。

唯一允许 suppress 目标类别的例外，是 @compatibility(is_backward_compatible=True) 装饰的函数。PyTorch 有个向后兼容测试，会拿 inspect.signature 的字符串跟 golden 文件比对，加个 -> None 都会让比对失败：

@compatibility(is_backward_compatible=True)
def my_function(  # pyrefly: ignore[unannotated-return]
    self,
    arg1,  # 这里也不能加类型
):
    ...

一个例外，反而证明了规则的严肃性。除此之外还散落着一堆细节规范，每一条对应一种常见的踩坑：

• 语法走 PEP 604：int | None 和 list[str]，不再写 Optional 与 List
• ABC 从 collections.abc 导入：Callable、Sequence 和 Generator 这类
• 布尔谓词函数用 TypeGuard 或 TypeIs 区分正向与负向收窄
• 装饰器保签名用 ParamSpec，避免 Callable[..., Any] 把签名打废

ParamSpec 这条最值得拎出来讲。装饰器把 *args 和 **kwargs 转给内层函数时，普通的 Callable[..., Any] 会让签名彻底丢失，IDE 的自动补全也跟着废。用 ParamSpec 把参数规格透传过去，签名才完整：

_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

每一条都指向同一个目标：让注解既精确，又不破坏运行时行为。

使用场景

这个技能最直接的使用场景，是给 PyTorch 贡献代码。你改了一个文件，CI 里 pyrefly 在严格模式下扫到它没注解，照着走一遍七步，文件就能过关。它给你的是一个文件级的手术流程，不是仓库级的整体方案。

但它的适用边界很窄，得先说清楚。前提是项目里有 pyrefly.toml，而且 pyrefly、lintrunner 和测试器都在 PATH 上。技能明确说，缺任何一个就先停下来问要不要激活 conda 环境，别自己装、别乱替代。这是从仓库的 CLAUDE.md 继承来的规矩。

换个角度，就算你不碰 PyTorch，这套注解纪律本身也能搬走。object 优先于 Any、return 位置警惕宽类型、ParamSpec 保签名，这些判断规则在任何用了严格类型检查的 Python 项目里都成立。技能绑定的具体命令是 PyTorch 的，绑定的判断力是通用的。

它还有一个隐性用途，是当 Python 类型注解的教学样本。网上大部分类型教程还在堆 PEP 484 的 Optional[T] 写法，泛泛而谈，落地时还是会卡。这份技能讲的是 PEP 604 之后怎么写、什么时候该收什么时候该放。object 跟 Any 的差异是什么，return 位置为什么不能写太宽，ParamSpec 到底在保什么。这些问题都被翻译成了可直接套用的判断规则，不是抽象的口号。对类型系统已经入门的人，这份技能是进阶读物；对还在写 Optional[T] 的人，这份技能是把人拍醒的那一下。读它比读泛泛的类型教程性价比高得多，而且不会被过时的 PEP 484 写法带偏。

洞察与反思

把它跟 pyrefly 自带的 pyrefly infer 放一起看，定位差异就出来了。infer 自动往源码里写推断出的注解，走的是批量加纯机械的路线。这个技能是手动的，需要带判断地做决策，会让你去读调用点，在那条放宽阶梯里认真选。前者解决一个”快”字，后者解决一个”对”字。

这俩不是重复，是互补。infer 吐出来的注解经常 Any 泛滥，恰恰是这个技能最忌讳的那种”看起来动态就甩 Any”的惰性。一个负责启动，一个负责收尾把关。

而 PyTorch 之所以要这么较真，根源在 Pyrefly 的速度。它把检查时间压到了秒级，让逐文件严格化变成了一件可以反复迭代的事：

它的局限也实在。这个技能假设你已经很熟 Python 类型系统，PEP 604、TypeVar、TypeGuard 这些概念它不会从头教你。而且它深度绑定 PyTorch 的 lintrunner 和 @compatibility 测试，别家仓库直接套会踩空。它是给熟手的高阶工具，不是入门教程。

但要说这个技能最大的价值，是它示范了”好技能该把判断写成规则”。大部分类型注解教程都在堆语法，这个技能却在把”什么时候该收、什么时候该放”这种没法明说的经验，翻译成一条条可执行的规则。语法一天能学会，这种边界判断才是需要沉淀成文档的东西。

从平台角度看，这是 PyTorch 官方在 Smithery 上放出的又一份”内部工作流外化”产物。跟 docstring、issue-triage 那批一样，它们不追求通用，只追求”在自己仓库里能复现”。这种组织背书的技能越来越多，说明 Skills 生态开始从个人玩具，长出了可复用的工程资产。

资源地址

总结

pyrefly-type-coverage 做的，本质是把”给一个文件上类型强度”这件有门槛的活，拆成七步加一套注解纪律。

它最值得学的是那条 never-suppress 的红线和那条放宽阶梯。两者合起来回答了一个所有类型检查都躲不开的问题：什么时候坚持精确，什么时候允许妥协。答案是，目标类别永不妥协，非目标类别用 ignore 做最后手段，中间用 object 到 Any 的四级阶梯过渡。

如果你在给 PyTorch 贡献代码，或者你维护的项目正在切 pyrefly 严格模式，这份技能值得花二十分钟读一遍。它不会替你写注解，但它能保证你写出来的注解，扛得住 CI 和 reviewer 的双重审查。