Python Refactor 是一个专注于 Python 代码重构的技能，目标是把复杂、纠缠的代码转化为清晰、可维护且行为等价的实现。它采用分阶段工作流，强调安全优先与持续验证，适合在需要提升代码可读性、可维护性或进行遗留代码现代化时使用。
用途
该技能在以下情况触发：用户明确要求“可读”“可维护”“干净”或“重构”代码；代码审查指出理解或维护问题；遗留代码现代化；新人上手或教学场景；复杂度指标超过阈值。典型红旗信号包括：文件超过 500 行且函数分散、存在全局状态、多个 global 语句、没有清晰的模块/类组织、配置与业务逻辑混杂。
不适用场景：代码对性能至关重要且性能分析表明需优先优化性能；代码计划删除或替换；外部依赖需要向上游贡献；用户明确要求性能优化优先于可读性。
主要能力
技能围绕四阶段工作流展开：
-
分析阶段：通读代码库，识别可读性问题（脚本式/全局状态、上帝对象、嵌套条件、长函数、魔法数字、晦涩命名），评估架构是否符合 OOP 原则，测量复杂度指标，运行 lint 分析，检查测试覆盖并填补缺口，输出按影响和风险排序的问题列表。
-
规划阶段：将变更分类为非破坏性（重命名、文档、类型提示）和破坏性（移除全局、删除函数、替换 API）。破坏性变更必须制定迁移计划：搜索所有用法、记录每个用法、评估风险、绘制依赖图、制定测试策略、按最安全到最高风险排序、记录预期指标改进，输出重构计划、迁移计划、测试策略和回滚计划。
-
执行阶段：非破坏性变更可随时进行；破坏性变更遵循严格协议：创建新结构（不删除）→搜索所有用法→创建迁移清单→逐个迁移并每次运行静态分析和测试→验证迁移完成→仅在 100% 迁移验证后移除旧代码。执行规则包括：绝不跳过迁移清单、静态分析先于测试、一次只应用一种模式、原子候选、任何错误立即停止修复或回滚。
-
验证阶段：先运行静态分析（flake8 检查未定义名称、未使用导入、完整质量检查），再运行完整测试套件要求 100% 通过，验证架构（全局状态消除/封装、模块/类组织、职责分离、SOLID 合规），对比前后指标，检查性能回退，生成总结报告。若性能下降超过 10%、公共 API 签名变更、测试覆盖下降或重大架构变更，则标记人工审查。
使用方式
技能提供重构模式目录，包括：守卫子句、提取方法、字典分发、match 语句（Python 3.10+）、命名布尔条件、封装全局状态、按职责分组相关函数、创建领域模型（dataclass + enum）、应用依赖注入。命名约定涵盖变量、函数、常量、类。反模式修复按优先级排列：关键（脚本式/过程式代码与全局状态、上帝对象/上帝类）、高（复杂嵌套条件超过 3 层、长函数超过 30 行、魔法数字、晦涩命名、缺少类型提示、缺少文档字符串）、中（重复代码、基本类型偏执、长参数列表超过 5 个）、低（命名不一致、冗余注释、未使用导入）。
工具链推荐：Ruff + Complexipy（新项目推荐），安装命令为 uv tool install ruff complexipy radon wily；常用命令包括 ruff check src/、complexipy src/ --max-complexity-allowed 15、radon mi src/ -s。也支持 flake8 + 精选插件。多指标分析脚本 scripts/analyze_multi_metrics.py 结合 complexipy、radon 和可维护性指数。指标目标：圈复杂度每函数 < 10（警告 15，错误 20），认知复杂度每函数 < 15（警告 20），函数长度 < 30 行（警告 50），嵌套深度 ≤ 3 层，公共函数文档字符串覆盖率 > 80%，公共 API 类型提示覆盖率 > 90%。
适用场景
适合需要深度重构 Python 模块、降低复杂度、转换为 OOP 架构、提升可读性和可维护性的场景。与 clean-code 技能相比，clean-code 适合多语言表面清理（重命名局部变量、改进注释、简化结构），回归风险最低；python-refactor-method 适合 Python 专属深度重构（OOP 转换、SOLID、复杂度指标、迁移清单、基准验证）。升级路径为 clean-code → python-refactor-method。
限制
无法改进算法复杂度（属于算法变更）；无法添加代码或注释中不存在的领域知识；没有测试无法保证正确性；风格偏好因团队而异，需按团队约定调整。此外，性能关键代码应先分析、计划删除的代码、外部依赖（应向上游贡献）、无人需要修改的稳定遗留代码，均不建议重构。