规则系统

相关源文件

• tests/conftest.py
• tests/rules/test_hostscli.py
• tests/rules/test_sudo.py
• tests/test_corrector.py
• tests/test_types.py
• tests/utils.py
• thefuck/corrector.py
• thefuck/rules/hostscli.py
• thefuck/rules/sudo.py
• thefuck/types.py

规则系统是 TheFuck 中驱动命令纠错的核心机制。它定义了如何将不正确的 Shell 命令与潜在的修复方法匹配，以及如何生成、优先排序和向用户呈现这些纠正。该系统使 TheFuck 能够处理跨不同 Shell 和命令上下文的各种命令行错误。

有关启用或禁用规则的配置信息，请参阅配置。

核心组件

规则系统由几个关键组件组成，它们协同工作以识别和修复命令错误

来源: thefuck/types.py12-262

Command 类

The Command 类表示一个需要纠正的用户 Shell 命令

• script: 用户输入的命令字符串
• output: 命令产生的输出（通常是错误消息）
• script_parts: 将命令拆分为多个部分（便于解析）

Commands 通常使用 from_raw_script 类方法从原始 Shell 输入创建，该方法会捕获命令及其输出。

来源: thefuck/types.py12-82

Rule 类

The Rule 类定义了如何识别特定的命令错误以及如何修复它们

• name: 规则的唯一标识符
• match: 确定规则是否适用于给定命令的函数
• get_new_command: 生成匹配命令的纠正（多个）的函数
• enabled_by_default: 规则是否在没有显式配置的情况下启用
• priority: 决定纠正的呈现顺序
• side_effect: 发生纠正时应执行的操作的可选函数
• requires_output: 规则是否需要命令输出才能匹配

Rules 通常从 TheFuck 的规则目录中的 Python 模块加载。

来源: thefuck/types.py85-198

CorrectedCommand 类

The CorrectedCommand 类表示一个建议的错误命令修复

• script: 纠正后的命令字符串
• side_effect: 应用纠正时要运行的可选函数
• priority: 确定有多个纠正可用时的顺序

当选择并运行一个纠正后的命令时，它可以根据需要修改 Shell 历史记录并执行副作用。

来源: thefuck/types.py201-262

规则执行流程

规则系统在处理命令时遵循特定的流程

来源: thefuck/corrector.py81-92 thefuck/types.py168-198

当命令失败并调用 TheFuck 时，系统会

1. 从失败的命令创建一个 Command 对象
2. 从各种来源加载所有启用的规则
3. 通过其 match 函数测试每条规则是否适用于该命令
4. 对于匹配的规则，通过 get_new_command 生成纠正后的命令
5. 按优先级组织纠正并删除重复项
6. 向用户呈现纠正（或自动应用最高优先级的纠正）

这个过程的核心实现在 get_corrected_commands 函数中

来源: thefuck/corrector.py81-92

规则来源和组织

TheFuck 从多个来源加载规则，并以分层结构进行组织

来源: thefuck/corrector.py8-49

规则从三个主要来源加载

1. 捆绑规则: TheFuck 附带的默认规则
2. 用户规则: 用户在 ~/.thefuck/rules 中创建的自定义规则
3. 第三方规则: 来自名称以 thefuck_contrib_ 开头的 Python 包的规则

加载过程由 get_rules_import_paths 和 get_loaded_rules 函数处理，它们会发现并加载来自这些来源的规则模块。

来源: thefuck/corrector.py8-49

规则的结构

TheFuck 中的每个规则都遵循相似的结构。以下是 sudo 规则的一个示例

来源: thefuck/rules/sudo.py31-47

每个规则模块至少必须定义

1. 一个 match 函数，该函数接收一个 Command 对象并返回 True，表示规则是否适用
2. 一个 get_new_command 函数，该函数接收一个 Command 对象并返回一个字符串或字符串列表，包含纠正后的命令

可选属性包括

• priority (默认值: 1000)
• enabled_by_default (默认值: True)
• requires_output (默认值: True)
• side_effect (默认值: None)

来源: thefuck/types.py85-98 thefuck/types.py147-153

规则匹配和执行

当一条规则被测试以匹配一个命令时，会发生几个步骤

1. 检查规则的 is_enabled 属性以确定它是否处于活动状态
2. 如果已启用，则调用 is_match 方法，该方法会
   • 检查是否需要输出以及输出是否可用
   • 调用规则的 match 函数，并将命令传递给它
   • 捕获并记录任何异常
3. 对于匹配的规则，会调用 get_corrected_commands，该函数会
   • 调用 get_new_command 来生成纠正（多个）
   • 将每个纠正包装在 CorrectedCommand 对象中
   • 根据规则的优先级分配优先级

此过程是容错的，会记录异常而不是在规则遇到错误时失败。

来源: thefuck/types.py168-198

规则优先级

TheFuck 使用优先级系统来确定建议纠正的顺序

来源: thefuck/corrector.py52-78 thefuck/types.py185-198

每个规则都有一个基础优先级（默认为 1000，数值越低优先级越高）。当一个规则生成多个纠正时，它们会获得递增的优先级

• 第一个纠正: rule_priority × 1
• 第二个纠正: rule_priority × 2
• 第三个纠正: rule_priority × 3

organize_commands 函数按优先级对所有纠正进行排序并删除重复项，确保将最相关的纠正排在最前面。

来源: thefuck/corrector.py52-78

创建自定义规则

要创建自定义规则

1. 在 ~/.thefuck/rules 中创建一个 Python 文件（例如，~/.thefuck/rules/my_rule.py）
2. 定义必需的 match 和 get_new_command 函数
3. 可选地定义其他属性，如 priority、enabled_by_default 等

一个简单自定义规则的示例

自定义规则在 TheFuck 启动时自动加载，并遵循与捆绑规则相同的执行流程。

来源： thefuck/corrector.py22-37 thefuck/types.py129-153

高级规则功能

副作用

规则可以定义一个 side_effect 函数，在应用更正时执行额外的操作

当选择更正时，CorrectedCommand 的 run 方法会执行副作用。

来源： thefuck/types.py86-98 thefuck/types.py247-254

装饰器支持

许多规则使用装饰器来添加通用功能

常见装饰器包括

• @sudo_support：使规则在有或没有 sudo 前缀的情况下都能工作
• @for_app：将规则限制在特定应用程序
• @eager：在不需要命令输出的情况下应用规则

来源： thefuck/rules/hostscli.py9-10

规则系统配置

规则系统可以通过 TheFuck 的设置进行配置

• rules：要启用的规则列表（将覆盖 enabled_by_default）
• exclude_rules：要明确禁用的规则列表
• priority：映射规则名称到自定义优先级的字典
• require_confirmation：在应用更正前是否要求确认
• repeat：如果更正后的命令失败，是否重试 TheFuck

这些设置在 TheFuck 启动时加载，并影响规则的选择和应用方式。

来源： thefuck/types.py155-166 thefuck/types.py231-245

有关配置的更多详细信息，请参阅 设置文件。