本指南详述了将 fastkml Python 包从 mypy 迁移至 ty 和 pyrefly 的过程。它强调需同时运行 ty 和 pyrefly，因为两者能捕获不同的错误子集，从而比单一检查器提供更全面的视图。流程始于在代码变更之前，为两种工具建立基准错误计数。高效迁移的关键在于识别并解决系统性根本原因，这些原因通常与可选 C 扩展后端相关，而非逐个文件修复错误。工具暴露的真实 bug，尤其是涉及 Optional/union 收窄和仅位置参数的 stub 的问题，应予以修正。来自测试文件的噪声，特别是“构造后未收窄即访问”类问题，应使用作用域规则进行批量抑制。本指南建议开启严格预设，随后逐步启用特定规则，同时明确剔除那些导致过度机械性变更的规则。验证工作包括确保两种工具均无报错、完整测试套件通过且代码检查器（linters）无问题。迁移前，需彻底分析现有的 mypy 配置，以理解 ty 和 pyrefly 需要匹配或超越的严格度基准。梳理 mypy 配置涉及将其设置映射到其大致对应的 ty/pyrefly 等价项，并移除过时的按模块禁用的错误代码覆盖。安装 ty 和 pyrefly 后，获取按错误类型分类的基准错误计数，以及按文件分类的计数至关重要；后者通常能揭示系统性原因。若存在带有广泛抑制的局部迁移，应将其视为警示信号，并移除抑制以查看真实基准。最具杠杆效应的举措是修复两种检查器均标记出的架构不匹配问题。一种常见模式涉及通过 try/except 导入处理可选后端，其修复方案通常是使用 if TYPE_CHECKING: 代码块，以便类型检查器能看到更丰富后端接口的 stub。潜在陷阱包括 # type: ignore[code] 注释的非可移植性、pyrefly 的 TOML 键大小写问题、pyrefly 的数组表语法在交错使用时的脆弱性，以及 Protocol 无法直接赋值给具体类参数的问题。在整个过程中，对工具行为和配置的仔细验证至关重要。