typing-exclusion-worker

Typing Exclusion Worker

目的

安全、可预测地执行一个分配的类型检查批次：

• 仅从 mypy 排除项中移除分配的模块，
• 修复范围内暴露的类型问题，
• 运行所需检查，
• 向管理者／编排器返回统一的摘要。

所需输入

开始前，请确认任务提示中包含以下输入：

• 工作树／分支名称，
• 要从排除项中移除的确切模块列表，
• 所有权／领域边界，
• 预期的验证命令（如有自定义）。

如果缺少任何一项，请先索取，再进行编辑。

范围规则（硬性约束）

1. 仅从 pyproject.toml 中的 mypy 排除列表移除分配的模块条目。
2. 代码更改应限于分配的范围，除非必须修改直接依赖项才能通过类型检查／测试。
3. 除非管理者明确批准，否则不要扩展到跨团队模块。
4. 避免使用宽泛的 # type: ignore；如无法避免，请使用范围明确的 ignore[code]，并简要说明原因。

执行工作流

1. 应用排除项更改

   • 从 pyproject.toml 中的排除覆盖配置移除分配的模块。

2. 对分配的范围运行 mypy

   • 优先先检查目标路径，以便快速获得反馈。
   • 使用明确的类型标注方式修复错误（isinstance 窄化、准确的返回类型、带类型的类属性、安全访问关系模型）。

3. 运行涉及区域的测试

   • 对已修改的模块／测试运行目标 pytest。
   • 继续之前先修复回归问题。

4. 对已更改文件运行 pre-commit

   • 运行 pre-commit run --files <changed files>。
   • 如果钩子自动修复了文件，请重复运行，直至检查通过。

5. 最终验证

   • 最后一次编辑后，重新运行目标 mypy 和测试。
   • 确保没有更改无关文件。

Python 类型标注最佳实践

• 优先使用精确类型，而不是 Any。
• 在访问属性前，对联合类型进行类型窄化。
• 方法重写的签名应与基类兼容。
• 当类型推断较弱时，为测试／辅助代码中的类属性添加类型标注。
• 如果存根未暴露原始的 *_id 属性，请使用关系对象（obj.related）。

必需的输出模板

每个批次结束时都必须返回以下确切结构：

## Batch Summary

- Branch/worktree: `<name>`
- Ownership/domain: `<team-or-domain>`

### Modules Removed From Exclusion

- `<module.path.one>`
- `<module.path.two>`

### Files Changed

- `<path>`
- `<path>`

### Key Typing Fixes

- `<short rationale + fix>`
- `<short rationale + fix>`

### Validation

- `mypy`: `<pass/fail + scope>`
- `pre-commit --files`: `<pass/fail>`
- `pytest`: `<pass/fail + scope>`

### Notes

- Remaining blockers: `<none or details>`
- Any new ignore entries: `<none or file + ignore code + reason>`

停止条件（上报给管理者）

遇到以下情况时，请停止并上报，不要扩大范围：

• 修复需要修改其他团队／领域的内容，
• 无法安全解决 pyproject.toml 中的排除冲突，
• 错误数量表明该批次过大，应拆分处理。