用途：系统性诊断并解决 pyright/mypy 报告的 Python 类型检查错误，通过将错误分类并套用已验证的修复模式来处理。适用于 CI/CD 或本地类型检查报错、为无类型代码补充注解、重构后维持类型安全、调试“类型 X 不能赋值给 Y”、修复 Optional/None 处理、解决泛型参数错误、切换到严格类型检查模式，以及提交前作为质量门禁。不适用于 pytest 配置、导入校验或运行时错误（类型检查是静态的）。
主要能力：按六类错误归类——缺失类型注解、赋值类型不匹配、Optional/None 处理、泛型类型错误、属性/方法错误、导入/模块错误；提供对应修复模板，如补充注解、修正类型、加 None 检查、补泛型参数。附带自动化脚本：parse_pyright_errors.py 解析并归类错误，fix_missing_annotations.py 自动补注解，fix_optional_handling.py 修复 Optional 处理。
使用方式：先运行类型检查并捕获输出，例如 uv run pyright src/ --verbose > type_errors.txt；再解析归类，例如 uv run pyright src/ | python .claude/skills/debug-type-errors/scripts/parse_pyright_errors.py；随后套用修复模板，同一文件多处修改建议用 MultiEdit 批量处理；最后重新运行 pyright 验证。自动修复可先加 --dry-run 预览。
项目规则：不使用 Optional 配置参数（用 Settings 而非 Settings | None）；遇到 None 立即失败并抛 ValueError；服务方法统一返回 ServiceResult[T]；不返回裸 None；泛型必须写明参数如 list[str]。
限制与要求：需要 Python 3.11+、pyright（可用 uv pip install pyright 安装）及 pyrightconfig.json 配置。资料未提供具体收费、平台支持范围或效果数据。