# 高级规则操作：执行 Python 脚本

本文档介绍如何通过执行自定义 Python 脚本来扩展简单文本替换规则的功能。这一强大的功能允许您创建动态响应、与文件交互、调用外部 API 以及直接在语音识别工作流程中实现复杂的逻辑。

## 核心概念：`on_match_exec`

您现在可以告诉规则在其模式匹配时执行一个或多个 Python 脚本，而不仅仅是替换文本。这是通过将“on_match_exec”键添加到规则的选项字典中来完成的。

该脚本的主要工作是接收有关匹配的信息、执行操作并返回将用作新文本的最终字符串。

### 规则结构

带有脚本操作的规则如下所示：

__代码_块_0__
**要点：**
- `on_match_exec` 值必须是一个**列表**。
- 脚本与映射文件位于同一目录中，这就是为什么推荐使用“CONFIG_DIR / 'script_name.py'”来定义路径。

---

## 创建可执行脚本

为了让系统使用您的脚本，它必须遵循两个简单的规则：
1. 它必须是有效的 Python 文件（例如“my_script.py”）。
2. 它必须包含一个名为“execute(match_data)”的函数。

### `execute(match_data)` 函数

这是所有可执行脚本的标准入口点。当规则匹配时系统会自动调用该函数。

- **`match_data` (dict)：** 包含有关匹配的所有上下文的字典。
- **返回值（str）：** 函数**必须**返回一个字符串。该字符串将成为新的处理后的文本。

### `match_data` 字典

该字典是主应用程序和脚本之间的桥梁。它包含以下键：

* `'original_text'` (str)：应用当前规则的任何替换之前的全文字符串。
* `'text_after_replacement'` (str)：应用规则的基本替换字符串*之后*但调用脚本*之前*的文本。 （如果替换为“None”，则这将与“original_text”相同）。
* `'regex_match_obj'` (re.Match)：官方 Python 正则表达式匹配对象。这对于访问**捕获组**来说非常强大。您可以使用 `match_obj.group(1)`、`match_obj.group(2)` 等。
* `'rule_options'` (dict)：触发脚本的规则的完整选项字典。

---

## 示例

### 示例 1：获取当前时间（动态响应）

该脚本根据一天中的时间返回个性化问候语。

**1.规则（在您的地图文件中）：**
__代码_块_1__

**2.脚本（`get_current_time.py`）：**
__代码_块_2__
**用法：**
> **输入：**“现在几点了”
> **输出：** “下午好！现在是 14:30。”

### 示例 2：简单计算器（使用捕获组）

该脚本使用正则表达式中的捕获组来执行计算。

**1.规则（在您的地图文件中）：**
__代码_块_3__

**2. The Script (`calculator.py`):**
__代码_块_4__
**用法：**
> **输入：**“计算 55 加 10”
> **输出：**“结果是 65。”

### 示例 3：持久购物清单（文件 I/O）

此示例展示了一个脚本如何通过检查用户的原始文本来处理多个命令（添加、显示），以及如何通过写入文件来保存数据。

**1.规则（在您的地图文件中）：**
__代码_块_5__

**2.脚本（`shopping_list.py`）：**
__代码_块_6__
**用法：**
> **输入1：**“将牛奶添加到购物清单”
> **输出 1：** “好的，我已将‘牛奶’添加到购物清单中。”
>
> **输入2：**“显示购物清单”
> **输出 2：** “您的清单上有：牛奶。”

---

## 最佳实践

- **每个脚本一个作业：** 让脚本专注于单个任务（例如，“calculator.py”仅进行计算）。
- **错误处理：** 始终将脚本的逻辑包装在“try... except”块中，以防止它使整个应用程序崩溃。从“ except”块返回用户友好的错误消息。
- **外部库：** 您可以使用外部库（例如 `requests` 或 `wikipedia-api`），但必须确保它们已安装在您的 Python 环境中（`pip install <library-name>`）。
- **安全性：** 请注意，此功能可以执行任何 Python 代码。仅使用来自可信来源的脚本。