ruff-recursive-fix

Ruff 递归修复

概述

使用此技能，以可控的迭代式工作流通过 Ruff 强制执行代码质量。 它支持：

• 可选将范围限制到特定文件夹。
• 默认从 pyproject.toml 读取项目设置。
• 灵活调用 Ruff（uv、直接 ruff、python -m ruff 或等效方式）。
• 可选的每次运行规则覆盖（--select、--ignore、--extend-select、--extend-ignore）。
• 自动先执行安全、再执行不安全自动修复。
• 每轮修复后审查 diff。
• 递归重复，直到问题解决或需要决策。
• 仅在抑制有正当理由时，审慎使用内联 # noqa。

输入

运行前收集以下输入：

• target_path（可选）：要检查的文件夹或文件。为空表示整个仓库。
• ruff_runner（可选）：显式的 Ruff 命令前缀（例如 uv run、ruff、python -m ruff、pipx run ruff）。
• rules_select（可选）：逗号分隔的要强制执行的规则代码。
• rules_ignore（可选）：逗号分隔的要忽略的规则代码。
• extend_select（可选）：在不替换已配置默认值的情况下额外添加的规则。
• extend_ignore（可选）：在不替换已配置默认值的情况下额外忽略的规则。
• allow_unsafe_fixes（默认值：true）：是否运行 Ruff 不安全修复。
• ask_on_ambiguity（默认值：true）：当存在多个有效选择时，始终询问用户。

命令构造

根据输入构造 Ruff 命令。

0. 解析 Ruff 运行器

在构造命令前，确定可复用的 ruff_cmd 前缀。

解析顺序：

1. 如果提供了 ruff_runner，按原样使用。
2. 否则如果 uv 可用且 Ruff 通过 uv 管理，使用 uv run ruff。
3. 否则如果 ruff 在 PATH 上可用，使用 ruff。
4. 否则如果 Python 可用且该环境中安装了 Ruff，使用 python -m ruff。
5. 否则使用任何调用已安装 Ruff 的项目特定等效方式（例如 pipx run ruff），或停止并询问用户。

在工作流中的所有 check 和 format 命令中使用同一解析后的 ruff_cmd。

基础命令：

<ruff_cmd> check

格式化命令：

<ruff_cmd> format

带可选目标：

<ruff_cmd> format <target_path>

添加可选目标：

<ruff_cmd> check <target_path>

按需添加可选覆盖：

--select <codes>
--ignore <codes>
--extend-select <codes>
--extend-ignore <codes>

示例：

# Full project with defaults from pyproject.toml
ruff check

# One folder with defaults
python -m ruff check src/models

# Override to skip docs and TODO-like rules for this run
uv run ruff check src --extend-ignore D,TD

# Check only selected rules in a folder
ruff check src/data --select F,E9,I

工作流

1. 基线分析

1. 使用选定的范围和选项运行 <ruff_cmd> check。
2. 按类型分类问题：
   • 可自动修复的安全问题。
   • 可自动修复的不安全问题。
   • 无法自动修复。
3. 如果没有剩余问题，停止。

2. 安全自动修复轮次

1. 使用相同的范围/选项运行带 --fix 的 Ruff。
2. 仔细审查生成的 diff，确保语义正确性和风格一致性。
3. 在同一范围运行 <ruff_cmd> format。
4. 重新运行 <ruff_cmd> check 以刷新剩余问题。

3. 不安全自动修复轮次

仅当仍有问题且 allow_unsafe_fixes=true 时运行。

1. 使用相同的范围/选项运行带 --fix --unsafe-fixes 的 Ruff。
2. 仔细审查生成的 diff，优先关注行为敏感的编辑。
3. 在同一范围运行 <ruff_cmd> format。
4. 重新运行 <ruff_cmd> check。

4. 手动修复轮次

对于剩余问题：

1. 当存在清晰、安全的修正时，直接在代码中修复。
2. 保持编辑最小且局部。
3. 在同一范围运行 <ruff_cmd> format。
4. 重新运行 <ruff_cmd> check。

5. 歧义策略

如果在任何步骤存在多个有效解决方案，始终在继续前询问用户。 不要在等效选项之间静默选择。

6. 抑制决策（# noqa）

仅当以下所有条件均为真时使用抑制：

• 该规则与必需行为、公共 API、框架约定或可读性目标冲突。
• 重构与该规则的价值不成比例。
• 抑制范围窄且具体（单行，尽可能显式指定代码）。

指南：

• 优先使用 # noqa: <RULE> 而非宽泛的 # noqa。
• 对于不明显的抑制，添加简短原因注释。
• 如果存在两个或更多有效结果，始终询问用户偏好哪个选项。

7. 递归循环与停止条件

重复步骤 2 到 6，直到出现以下任一结果：

• <ruff_cmd> check 返回无问题。
• 剩余问题需要架构/产品决策。
• 剩余问题已通过记录的依据有意抑制。
• 重复循环没有取得进展。

每次循环迭代都必须在下一次 <ruff_cmd> check 之前包含 <ruff_cmd> format。

当检测不到进展时：

1. 总结被阻塞的规则和受影响的文件。
2. 提供有效选项和权衡。
3. 请用户选择。

质量门禁

在宣布完成之前：

• Ruff 对所选范围/选项未返回意外问题。
• 所有自动修复 diff 都已审查其正确性。
• 未经明确理由，不添加任何抑制。
• 任何可能影响行为的不安全修复都会向用户突出提示。
• 每次迭代都会执行 Ruff 格式化。

输出契约

在执行结束时，报告：

• 使用的范围和 Ruff 选项。
• 执行的迭代次数。
• 已修复问题的摘要。
• 手动修复列表。
• 带依据的抑制列表。
• 剩余问题（如有）以及所需的用户决策。

建议的提示词起始句

• “在整个仓库上使用默认配置运行 ruff-recursive-fix。”
• “仅在 src/models 上运行 ruff-recursive-fix，忽略 DOC 规则。”
• “在 tests 上使用 select F,E9,I 且不使用不安全修复来运行 ruff-recursive-fix。”
• “在 src/data 上运行 ruff-recursive-fix，并在添加任何 noqa 之前询问我。”