Ruff Python Linter 配置器

迁移 Ruff 时的配置难题

Python 项目长期维护后，常见的工具组合是 Flake8 做代码检查、isort 管理导入顺序、Black 统一代码格式。这三个工具各自有独立的配置文件和规则体系，比如项目根目录可能有 setup.cfg、.isort.cfg、pyproject.toml 等多个配置文件。

Ruff 用 Rust 编写，速度极快，它把代码检查和格式化合二为一，但这意味着不能简单地把 Flake8 的 .flake8 配置直接复制过去。isort 的 known_first_party、Black 的 line_length 在 Ruff 里对应的是 [tool.ruff.isort] 和 [tool.ruff.format] 的键，命名和位置都不一样。手动迁移不仅费时，还容易遗漏规则，导致 CI 通过但实际检查覆盖不全。

自动迁移与冲突解决

这个技能的核心工作是读取项目中已有的 Flake8、isort、Black 配置，生成一份优化后的 Ruff 配置。它把分散在多个文件里的规则映射到 pyproject.toml 的 [tool.ruff] 节，并自动处理规则冲突。

典型流程是这样的：

• 扫描项目根目录，识别 .flake8、setup.cfg、tox.ini 里的 Flake8 配置
• 读取 .isort.cfg 或 pyproject.toml 里的 [tool.isort] 节
• 检查 Black 的配置，比如 line_length、target_version
• 生成 [tool.ruff] 配置，把三个工具的规则合并进去
• 遇到冲突规则时自动选择优先级更高的那个

输出的 pyproject.toml 可以直接用于 Ruff，不需要额外修改。

适用边界

这个技能依赖上游 Ruff 的文档和规则定义。Ruff 的规则集与 Flake8 插件并不完全一一对应，某些 Flake8 插件提供的规则在 Ruff 中可能没有等价实现，或者名称不同。这种情况下生成的配置会缺失相应规则，需要手动补充。

另外，技能处理的是 静态配置文件 层面的迁移，不会修改项目代码本身。如果现有代码不满足 Ruff 的规则，生成配置后运行 ruff check 仍然会报错，需要开发者自己修复代码或调整规则。

Ruff 本身的安装和升级属于上游工具的范畴，技能只负责配置生成这一环节。