Ruff ty 生态变更的深度最小化：六阶段缩减循环与最终审计方法论

本文围绕 Ruff 仓库中 ty 类型检查器生态变更排查技能里的参考文档 advanced-minimization.md 展开，系统讲解当一个 mypy-primer 生态报告差异已在“基线 + PR 双二进制”上复现之后，如何将其最小化为单文件、无冗余 import 的可复现用例：包括最小化目标、六阶段缩减循环（reduction loop）、第三方依赖整包克隆与标准库内联策略，以及收尾时的最终审计（Final Audit）与证据链要求。读完本文，你可以掌握一套完整的“保留触发条件、逐级剥离代码、可验证回归”的最小化流程，并能结合仓库源码理解 ty 为何对第一方/第三方搜索路径做区分、vendored 标准库 stub 的真实来源与内联方法。

一、这份参考文档在 ty 生态排查工作流中的位置

advanced-minimization.md 是技能 minimizing-ty-ecosystem-changes 的参考文件，其开篇即明确了使用前提：

Use this reference after the reported difference reproduces against the copied base and PR binaries. （在报告差异已针对复制的基线与 PR 二进制复现之后，才使用本参考。）

也就是说，它不是排查的入口，而是“复现已完成、开始做最小化”阶段的操作规程。父技能 SKILL.md 定义了完整工作流的五条不变量，这些不变量直接决定了最小化阶段的每条规则：

1. 使用与 Actions 运行完全一致的 Ruff 修订、用户级 PR 配置、依赖截止时间、mypy-primer 修订、项目 Python 版本与严格度设置；
2. 先复现，后解释——在解释差异或手写更小示例之前，必须先复现报告中的项目差异；
3. 复制来的二进制与配置视为只读，每次缩减都要用两个二进制验证；
4. 每个候选用例必须从上一个已验证的候选推导而来，绝不替换为独立构造的示例；
5. 保留的是“底层触发条件”（underlying trigger），而不是诊断规则、消息或显示出来的类型。

本参考文档正是第 2 条“复现之后”到第 4、5 条“保真缩减”之间的执行细节。父技能还强调：匹配的诊断消息或显示的相同类型并不构成共同因果的证明，当输出含糊时，需要用精确修订的 debug 输出、有针对性的 reveal_type 或对应 Rust 调用点来对比原始与最小化后的触发条件——这一判断标准在本文第五节的最终审计中会被再次用到。

整个工作流的输入来自一个不可变的运行元数据清单，通常由 collect_ty_ecosystem_run_metadata.py 生成：脚本通过 gh run view 解析 Build ty (base) 日志中的 Merge base 与 PR commit、解析第一个 analyze-shards 日志中的 EXCLUDE_NEWER、ECOSYSTEM_ANALYZER_COMMIT 与 MERGE_BASE，并交叉校验两处 merge base 一致，最终输出包含 Ruff 双修订、ecosystem-analyzer 修订、mypy-primer 修订和每个项目的 CI Python 版本的结构化 JSON。这份清单里的“精确修订”就是后文反复强调的 git show <exact-revision> 的来源。

二、最小化目标（Target）：单文件、零可避免 import、最弱类型构造

参考文档给出了最小化结果的明确目标，逐条拆解如下：

• 单文件复现器（prefer a single-file reproducer）；
• 无可避免的第三方 import（no avoidable third-party imports）；
• 尽可能少的定义（few definitions）；
• 能演示该差异的最复杂程度最低的 typing 或语言特性（the least complex typing or language features that still demonstrate the difference）。

两条特殊的保留规则值得单独说明：

1. 特殊标准库模块：typing、abc、enum、types、typing_extensions 这类模块只有在“既不能直接删掉、也不能内联其定义仍保持行为”时才保留。换言之，默认立场是把这些模块的用法内联掉，只有内联失败才允许保留 import。
2. 第三方 import：只有在“识别出 ty 中存在依赖该库身份（identity）或第三方搜索路径分类（third-party search-path classification）的行为”之后，才允许保留第三方 import。

第二条规则的背后是 ty 模块解析器的真实设计：从源码结构看，crates/ty_module_resolver 负责把 import 解析到具体模块，其内部有 environment.rs、strategy.rs、typeshed.rs 等模块，typeshed.rs 正是标准库 stub 的来源接入点。一个库作为“已安装的第三方包”与作为“源码树中的第一方代码”在搜索路径分类上走不同的解析路径，某些诊断（例如 possibly-unresolved-reference 的判定、对包命名空间的识别）行为可能因此不同——这就是为什么最小化时不能随手把第三方 import 换成内联代码：一旦换了身份，差异可能随之消失，而消失的原因恰恰是你要研究的东西本身。

三、缩减循环（Reduction Loop）：六个阶段的严格规程

文档对缩减循环的总纲是：

系统性地从复现出的项目出发工作。永远不要跳到解释、手写复现器或猜测的相关代码子集。 按顺序执行以下阶段，每个阶段穷尽后再进入下一阶段。一次只做一个受控缩减，每次修改后运行两个复制来的 ty 二进制，只有当原始差异和底层触发条件仍然保持时才保留该缩减。每次成功缩减后回到第 1 步重新开始，因为它可能使更早的缩减成为可能。

阶段 1：删除无关文件

从复现出的完整项目出发，逐个删除与差异无关的文件。受控原则意味着一次只删一个（或一组明显相关的）文件，然后立刻用 ty-base 与 ty-pr 双二进制回归。这一步通常能砍掉生态项目里绝大多数的模块，是收益最高的阶段。

阶段 2：删除 import、定义、装饰器、注解、语句与分支

在文件内部，按“import、定义、装饰器、注解、语句、分支”的粒度继续裁剪。注意裁剪对象包括注解与装饰器——泛型注解、@dataclass 之类的装饰器经常是触发类型检查差异的关键，但也可能是无关噪声；对每一处都要做“删与不删”的双二进制对照。

阶段 3：把第一方定义内联进复现器

第一方（first-party）指项目源码树内的定义。凡是复现器 import 的本项目其他模块里的定义，都应逐个复制（内联）进复现文件，然后删掉对应 import 与被内联的原文件。内联后必须再次验证差异仍然存在——因为 ty 对“同名模块在不同文件中定义”与“直接在本文件定义”的处理可能存在微妙差别（例如 __future__、模块级 __all__、相对导入路径等）。

阶段 4：第三方依赖——先整包克隆，再做缩减

这是六阶段中最反直觉、也最容易出错的一步，文档的要求可以概括为“四个禁止、两个必须”：

• 禁止一开始就只复制“看起来相关文件”或“相关定义”；
• 禁止在依赖被完整克隆前对其做任何最小化；
• 必须把整个已安装的依赖（包括它提供的所有包目录和模块）复制到源码树中作为第一方代码，使用精确的已安装修订或版本；
• 必须在调整 import、验证“完整副本下差异仍然复现”之后，才允许开始从这个副本里删文件或定义。

还有一个关键的例外分支：如果完整副本改变了行为，原因是 ty 对该库做了特殊处理（special-cases），或者 ty 区分了第一方/第三方搜索路径，那么应当先识别出对应 ty 实现（在与报告匹配的被分析 Ruff 修订上），再决定保留原始 import。

这一步的工程价值在于：它保证你对第三方库的每一次删减都建立在与 CI 完全一致的依赖状态之上。CI 用的是带锁文件的依赖解析，本地随意 pip install 一个相近版本可能悄悄改变行为；而“整包克隆”把依赖从搜索路径上移除，变成纯粹的源码树，使后续缩减完全可控。

阶段 5：内联标准库定义——从 crates/ty_vendored 的精确修订取件

文档给出的标准库内联方法是：

Inline the relevant standard-library definitions from the analyzed revision of crates/ty_vendored, using git -C <ruff-checkout> show <exact-revision>:crates/ty_vendored/<path>; compare the merge-base and PR definitions when they differ.

即：用 git show 从被分析的精确修订（merge-base 或 PR 修订）中取出 crates/ty_vendored 下的标准库 stub 定义，内联进复现器；当两个修订的该定义不同（即该 PR 恰好改动了 vendored stub）时，必须对比两个版本。

结合仓库实际可以看清这里的细节。crates/ty_vendored/README.md 说明该 crate 内嵌了 typeshed 的标准库 stub，位于 crates/ty_vendored/vendor/typeshed，并由 source_commit.txt 记录当前对应的 typeshed 提交（当前仓库为 bc016545988403f13b2dd9b56e88b931683c80b1）；stub 每两周通过自动化 PR 同步。crates/ty_vendored/src/lib.rs 则显示这些 stub 在构建期被打包为 zip 并加载进 VendoredFileSystem，SOURCE_COMMIT 常量通过 include_str! 在编译期嵌入。此外，同步流程还会套用 typeshed_patches 目录下的补丁（如 0001-dict-get-object.patch 等，用于修改 dict/mapping 的 get 签名等）并加入 ty_extensions 中的扩展 stub。

这带来两条实操推论：

1. 工作区文件不等于被分析二进制的输入。父技能明确要求：查看 vendored 定义时用 git -C <ruff-checkout> show <exact-revision>:<repository-relative-path> 指定 merge-base 或 PR 修订，绝不能假设当前工作树文件与被分析的二进制一致，也不能切换共享 checkout 的 ref。
2. 如果 PR 本身修改了 vendored stub，同一标准库调用在 base 与 PR 下读到的是不同定义，差异的“底层触发条件”可能直接落在 stub 变更上；此时内联时要用两个修订各自的定义分别验证。

阶段 6：用更简单的构造替换复杂构造

Replace complex constructs with simpler equivalents, such as removing a walrus expression or replacing a protocol when the difference survives.

例如海象运算符可以展开为“先赋值再判断”的两步写法，Protocol 类可以换成普通 duck-typing 结构。原则与前面一致：替换后差异与触发条件仍然保持，才保留该替换。

循环终止条件：穷尽式扫描，而非“看起来够小”

文档对停止条件的规定非常强硬：

Repeat the full loop until an exhaustive pass through every stage finds no further reduction that preserves the difference. Do not stop merely because the likely cause is understood or the reproducer is already small.

即：重复完整循环，直到对所有阶段做一次穷尽扫描、找不到任何能保持差异的进一步缩减为止。不能因为“已经理解了可能的原因”或“复现器已经很小”而提前停止。同时，每次成功缩减后都要回到第 1 步——因为删除文件/定义可能暴露出之前无法删除的其他内容（典型的级联缩减）。

四、双二进制验证：为什么每次修改都要跑两次

缩减循环中“run both copied ty binaries after every change”的要求，来源于父技能 SKILL.md 的“Reproduce”一节：两个二进制分别在 merge-base 与 PR 修订上以 --profile profiling 构建（CARGO_PROFILE_PROFILING_DEBUG=line-tables-only），复制为 ty-base 与 ty-pr；复现判定要求逐条核对详细报告中的差异，包括重复诊断与两侧的退出状态（普通诊断退出码为 1，不代表复现失败；panic 类失败则需比较 Rust panic 位置/关键因果帧与 panic 载荷这一“稳定指纹”来判定）。

在最小化阶段，这一双跑纪律的意义是：你要保持的不只是“PR 侧出现了该诊断”，而是“base 与 PR 之间的差异”。单次运行无法区分这两者——PR 侧诊断可能在 base 上同样存在，只是报告阈值或严格度导致未显示；只有双二进制对照才能确认“差异”这一因果载体在缩减后仍然成立。同时，PR 侧运行使用用户级配置（从 .github/ty-ecosystem.toml 安装为 XDG_CONFIG_HOME/ty/ty.toml），并按详细报告中的 strict / non-strict 标签决定是否追加 --config analysis.strict-equality-semantics=true --config analysis.strict-generic-narrowing=true，这与 CI 的生态分析模式保持一致。

五、最终审计（Final Audit）：对每个幸存 import 的问责

缩减循环收敛之后，参考文档要求再做一次“最终审计”，其强度高于循环本身——尝试删除每一个仍然存在的 import 并内联其定义，包括残留的第三方与标准库定义：

1. 保留任何 import 的前提：验证过“既删不掉、内联也不保持底层行为”。
2. 第三方 import 的额外验证：其模块身份（module identity）或第三方搜索路径分类是差异所必需的，并且已定位到 ty 中实现该行为的相应位置（在被分析的 Ruff 修订上）。
3. 不构成保留理由的情形：便利性、熟悉的 API、类名匹配、保留诊断消息中的模块拼写——这些都不算。
4. 记录要求：为每个幸存 import 记录它为何必要；第三方 import 还要记录 ty 在何处实现了相关行为。这些记录作为工作证据保留，是否进入最终交付物由调用方决定（父技能的 Return 一节要求把 import-audit 与 reduction notes 同报告用 Markdown 分开返回）。
5. 验证缩减链：检查“从最终复现器到原始生态入口”的缩减链是否完整连接；当诊断输出含糊时，还要确认它保留了原始的因果指纹（causal fingerprint）。
6. 失败处理：某个必要检查失败则继续调查；如果真正的外部阻塞导致无法完成，应当报告阻塞并将最小化标记为不完整，而不是把无关示例或原始摘录包装成“已最小化的结果”。
7. 清理：调查结束后删除临时创建的项目与依赖副本。

这里的“缩减链”概念呼应了父技能第 4 条不变量：每个候选都必须能从上一候选推导出来。最终审计时这条链应该可以被逐步回放——原始生态项目 → 删除无关文件 → 裁剪定义 → 内联第一方 → （可选）克隆并缩减第三方 → 内联标准库 → 替换复杂构造 → 单文件复现器——每一步都有“双二进制差异保持”的验证记录。

六、方法论小结：从源码结构看这套规程的设计意图

把文档规则与仓库实现对照，可以归纳出这条最小化规程背后的几个设计意图：

• 二进制是行为神谕（behavioral oracle）。ty 内部类型复杂，父技能明确指出“profiling 二进制保持行为神谕地位”，需要精确修订 debug 二进制来辨认含糊的内部类型时要向主代理申请，而不是凭当前工作树代码猜测。最小化循环因此被设计成“纯输入输出验证”：只关心双二进制的差异是否保持，不依赖对实现的理解——这也是“不要跳到解释”禁令的原因。
• 身份即行为。ty 的模块解析区分第一方源码树、第三方搜索路径与 vendored 标准库（分别对应 crates/ty_module_resolver 的解析策略与 crates/ty_vendored 的 VendoredFileSystem）。因此最小化必须把“代码内容”与“模块身份”分开处理：先保内容后动身份（阶段 4 的整包克隆），或明确识别身份敏感行为后再动（例外分支）。
• 精确修订优先于“最新版”。生态差异由两个历史修订上的二进制产生，vendored stub 也可能在 PR 中被修改，所以一切输入（依赖、stub、配置、Python 版本）都要从不可变清单取精确值，这与 collect_ty_ecosystem_run_metadata.py “无法确定唯一值就停止、绝不用本地默认替代”的错误处理哲学一致。
• 诚实的不完整性。规程把“标记为不完整并报告阻塞”写为合法出口，把“用原始摘录冒充最小化结果”列为禁止项，保证这条流水线产出的复现器在证据意义上是可信的。

七、实操检查清单

按参考文档整理成可执行清单，便于在实际调查中逐条打勾：

1. 确认双二进制（ty-base、ty-pr）与用户级配置已就位，且复现器当前能复现报告差异（含重复诊断与退出状态）。
2. 阶段 1–6 按序执行，每次一个受控缩减，每次双二进制回归；差异或触发条件消失则回滚。
3. 第三方依赖：先以精确版本整包克隆进源码树 → 调 import → 验证仍复现 → 才开始删减；若整包克隆改变行为，先定位 ty 中身份/搜索路径相关的实现。
4. 标准库内联一律 git show <exact-revision>:crates/ty_vendored/<path> 取件，两个修订的 stub 不同时分别对比。
5. 每次成功缩减后回到阶段 1 重扫。
6. 收敛后做最终审计：逐 import 删除/内联验证，第三方 import 附“ty 实现位置”证据；记录所有幸存理由。
7. 校验缩减链完整连接原始生态入口；检查失败则继续，外部阻塞则如实标记不完整。
8. 清理临时项目与依赖副本。

这套规程的价值不在任何单条命令，而在于它把“最小化”从一项依赖灵感的操作，变成了一条可审计、可回放、可被他人复核的证据链——这正是 Ruff 团队在持续跟进数百个生态项目行为变化时能维持复现器质量的工程基础。