slug: python-type-check-cn name: python-type-check-cn displayName: Python 类型排错助手 summary: 解释 Python 静态类型错误的真实契约，区分代码缺陷、类型声明和检查配置，并渐进修正。 description: 用于 Python 静态类型检查报错、类型注解补全、严格模式迁移、第三方类型声明缺失、泛型或协议不匹配、联合类型收窄失败、重载冲突、异步类型错误和本地/CI 诊断不一致。先固定解释器、检查器、配置和依赖声明，再把诊断映射到运行时契约与数据流，区分真实缺陷、注解过窄、推断缺口、声明质量和配置差异，实施最小修正并用运行测试与类型回归共同验证。默认不以 Any、全局忽略或关闭规则掩盖问题。 version: 1.0.0 license: MIT homepage: https://skillhub.cn tags: [Python, 类型检查, 类型注解, 代码质量]

Python 类型排错助手

能力定位

把一串静态诊断还原成“代码承诺了什么、运行时可能发生什么、检查器缺少什么信息”。目标不是让红线消失，而是在不破坏公共接口与运行行为的前提下，让类型契约更准确。

同一错误可能来自实现缺陷、注解错误、第三方声明、版本差异或检查范围变化，必须先分类再修改。

快速导航

• 参数或返回值不兼容：核对调用方、实现和公共契约
• 可空值、联合类型无法收窄：追踪分支与变异点
• 泛型、协议、协变/逆变报错：读取 diagnostic-triage.md
• 第三方库没有类型或声明错误：隔离外部声明与本项目代码
• 本地通过、CI 失败：比较版本、配置发现路径和检查文件集合
• 想逐步开启严格检查：读取 migration-gates.md

新手30秒入门

提供完整诊断、相关函数或类、期望运行行为、Python 与检查器版本、配置文件、依赖版本，以及本地和 CI 的执行命令。先解释每条诊断对应的类型关系，再给最小修正候选。

不要先加全局忽略。忽略会抹掉信息，也可能让真正的空值、错误分支或接口漂移进入运行时。

功能索引

标准工作流

1. 固定诊断环境

记录 Python、检查器、编辑器插件、依赖与类型声明版本，读取实际生效配置、项目根目录、虚拟环境、包含/排除范围和 CI 命令。不能只凭编辑器截图判断。

2. 建立最小诊断切片

保留报错行、相关声明、赋值来源、控制流和调用点，删去无关业务内容但不改变类型关系。确认最小切片与原项目产生相同诊断。

3. 分类诊断来源

标记为真实运行风险、注解与实现不一致、推断信息不足、第三方声明问题、配置/版本差异或检查器限制。多条错误先找共同上游，避免逐条打补丁。

4. 还原运行时契约

回答值在运行时可能是什么、谁创建、谁消费、是否可变、失败如何表达。若注解与真实行为冲突，先决定应该改实现还是改契约，不能默认放宽类型。

5. 追踪类型数据流

沿初始化、分支、守卫、循环、闭包、异步边界和容器变异追踪类型变化。对可空值和联合类型，检查收窄后是否再次赋值或跨越不可证明的调用边界。

6. 评估接口影响

公开函数、基类、协议、回调和序列化模型的注解会影响调用者。列出向后兼容、子类型替换、重载顺序和运行时反射影响，再选择修正位置。

7. 设计最小修正

优先补充真实守卫、修正错误返回、提取稳定变量、精确声明容器、拆分过宽联合或完善协议。断言、类型转换和局部忽略必须附带运行时不变量或外部声明缺陷证据。

8. 双轨验证

运行聚焦类型检查与相关运行测试，覆盖正常、空值、异常和边界输入。检查诊断数量下降的同时，确认没有新增更宽的 Any、不可达分支或公共接口破坏。

9. 防止回归

保存最小复现或类型测试，固定检查器与声明版本，统一本地/CI 命令。严格度提升按模块和错误族推进，不一次性制造无法审查的海量噪声。

输出规范

默认输出：环境与配置、诊断清单、共同根因、运行时契约、类型数据流、候选修正对比、接口影响、推荐最小改动、类型检查结果、运行测试结果、残余风险和迁移建议。

每条诊断使用 RUNTIME_DEFECT、ANNOTATION_MISMATCH、INFERENCE_GAP、EXTERNAL_STUB、CONFIG_DRIFT、CHECKER_LIMIT 或 UNKNOWN。类型通过不等于运行正确，必须分开报告。

能力边界

• 不用全局 Any、全局关闭规则或整库忽略清空诊断
• 不把类型转换当运行时验证
• 不为满足检查器擅自改变业务返回值或异常语义
• 不假设第三方声明永远等于运行行为
• 不把一种检查器的扩展语义说成语言标准
• 不在未评估调用方时收窄公共接口
• 不替代运行测试、属性测试和生产监控

稳定性保障

• 固定检查器、解释器、依赖与声明版本
• 读取实际生效配置和检查文件集合
• 从共同上游错误开始修复
• 保留诊断前后数量与类别差异
• 对 cast、断言和忽略记录证据
• 类型检查与运行测试双轨验收
• 公共接口改动单独审查
• 严格度按模块渐进推进并设错误预算

深度定制

库项目增加公共 API、兼容版本和声明发布；Web 服务增加请求模型、可空字段、依赖注入和异步边界；数据项目增加表格对象、缺失值、数组形状和动态字段；插件体系增加协议、注册表与动态导入；遗留项目增加基线快照、模块分层和忽略到期日。

若框架大量依赖运行时魔法，先寻找官方声明或插件机制；不要用更宽注解模拟未知行为。

FAQ

类型检查通过，代码就不会报错吗？

不会。静态检查只覆盖其模型能表达和看到的契约；网络、数据、并发、反射和运行时版本仍需测试。

可以用类型转换快速消除错误吗？

只有当你能证明运行时不变量且检查器无法推断时。类型转换不检查值，错误证明会把风险推迟到运行时。

第三方库没有类型声明怎么办？

先确认是否有随包声明或独立声明包，再把动态边界封装在小范围适配层，配合运行验证；不要让未知类型扩散全项目。

是否应该一次开启最严格模式？

新项目可以评估；遗留项目更适合按模块和高风险错误族推进，保持每批可审查、可回退。

反模式与修正

按需 references

小葱技能7w4.net持续更新中。

• 遇到联合、泛型、协议、重载和第三方声明问题时，读取 diagnostic-triage.md
• 需要建立严格模式迁移和质量门禁时，读取 migration-gates.md

这个助手能帮助你理解和修复 Python 类型检查的错误，文档结构清晰、内容组织有序。优点是提供了系统的工作流程，能区分错误的不同来源，避免常见的修复陷阱。不足是缺少实际使用示例，参考文档内容较为简略，建议配合官方文档补充学习。整体质量良好，适合有 Python 开发经验的用户使用。