Mypy 在 isinstance 分支中无法正确窄化联合类型（如 float | VObj）导致误报运算符错误，根本原因常是配置路径解析异常或类型信息丢失（如 Revealed type is "Any"），而非代码逻辑问题；通过显式指定 files 而非 packages 配置项可恢复完整类型上下文。

mypy 在 `isinstance` 分支中无法正确窄化联合类型（如 `float | vobj`）导致误报运算符错误，根本原因常是配置路径解析异常或类型信息丢失（如 `revealed type is "any"`），而非代码逻辑问题；通过显式指定 `files` 而非 `packages` 配置项可恢复完整类型上下文。

在大型 Python 项目中，Mypy 突然对原本正常工作的 isinstance 类型守卫报错（例如 "Unsupported operand types for / ("VObj" and "float")"），往往并非代码缺陷，而是类型检查器未能获取完整的模块类型上下文所致。典型表现为 reveal_type(vol) 返回 "Any" —— 这明确指示 Mypy 在该作用域丢失了对 VObj 的类型定义，使其在分支判断后仍以原始联合类型参与后续运算，从而触发误报。

这类问题在 Mypy 1.15+ 版本中更易复现，核心诱因是其配置文件发现机制变更：当使用 [tool.mypy].packages = ["rateslib"] 时，Mypy 可能因路径解析歧义或包结构复杂性，跳过部分子模块的类型导入，尤其在含 py.typed 标记的第三方风格库中。结果就是 VObj 被降级为 Any，isinstance(vol, VObj) 的类型守卫完全失效——Mypy 无法确认 vol 在 else 分支中一定不是 VObj，故保守地拒绝 / 运算。

✅ 可靠修复方案：改用 files 显式声明检查范围
将 pyproject.toml 中的 Mypy 配置从：

[tool.mypy]
packages = ["rateslib"]

替换为精确的源码路径：

[tool.mypy]
files = ["python/"]  # 指向实际源码目录
exclude = ["python/tests/"]

此举强制 Mypy 递归扫描指定目录下所有 .py 文件，确保 VObj 的完整类型定义（包括其 __getitem__ 签名、泛型约束等）被完整加载。验证方式：添加 reveal_type(vol) 后应输出类似 "VObj" 或 "float | VObj"，而非 "Any"。

⚠️ 其他关键注意事项

• 避免混用配置模式：packages 和 modules 主要面向已安装的第三方包，对本地开发库易产生路径解析不确定性；files 是主动、确定性的扫描策略，推荐作为默认选择。
• 验证 py.typed 生效：确保 python/rateslib/py.typed 文件存在且为空（或仅含注释），这是 PEP 561 要求的类型包声明，缺失会导致整个包被当作无类型处理。
• 临时诊断技巧：在报错行前插入 reveal_type(vol) 和 reveal_type(VObj)，若后者为 "Any"，即确认类型系统已中断，需优先检查配置与 py.typed。
• 不推荐的“修复”：添加 # type: ignore 或 cast(float, vol) 属于掩盖问题，会削弱类型安全；isinstance(vol, (float, VObj)) 也无法解决窄化失效，因联合类型本身未被分解。

总结而言，Mypy 的类型窄化能力高度依赖完整、可追溯的类型定义链。当 isinstance 守卫意外失效时，请优先排查配置是否导致类型信息丢失——这比重构业务逻辑更高效，也更符合类型检查工具的设计本质。