# 模糊映射宏和括号逻辑

Aura 支持在“FUZZY_MAP_pre.py”文件中对多个预处理规则进行分组，以便在触发“启动规则”后将它们作为内聚管道按顺序执行。本文档描述了该功能的设计理念、语法和执行流程。

## 核心设计原则

1. **零冗余**：组内的规则仍然是标准的Python元组：
`('replacement_text', r'regex_pattern', 阈值, flags_and_options)`
2. **双重可用性**：组内的单个规则是功能齐全的独立规则。如果该组未被触发，则它们将在父循环中正常评估。
3. **被动结束标记**：组的结束由被动规则条目定义，该条目本身从不匹配。它纯粹充当解析器的边界标记。
4. **混合回退（追加非匹配）**：当组处于活动状态时，每个内部规则都必须对输出做出贡献。如果内部规则的正则表达式与文本匹配，则会发生正常替换。如果不匹配，则将其替换文本附加到当前文本并添加一个空格。

---

## 语法和结构

宏组是通过在`FUZZY_MAP_pre.py`中的**开始规则**和**结束规则**之间包装一系列标准规则来定义的。

### 1. 开始规则
启动规则是匹配时触发宏的标准规则。它在其选项字典中包含一个“group_start”键：
__代码_块_0__

### 2. 内部规则
内部规则是按顺序放置在起始规则之后的标准规则。它们不需要任何特殊的元数据：
__代码_块_1__

### 3. 结束规则（被动标记）
结束规则在其选项字典中有一个“None”替换、一个空模式和一个“group_end”键：
__代码_块_2__

---

## 具体示例

这是在“FUZZY_MAP_pre.py”文件中定义的实际测试用例：

__代码_块_3__

### 执行流程场景：

* **场景 A（触发宏）**：
* 输入：`“启动沙箱mit apfel”`
* 预期流量：
1. 启动规则匹配 `"start sandbox"` 并将其替换为 `"Sandbox:"` -> 当前文本: `"Sandbox: mit apfel"`。
2. 触发“sandbox_test”组。
3. 我们在“Sandbox: mit apfel”上递归运行内部规则：
- 内部规则 1 匹配 `"apfel"` 并替换为 `"birne"` -> 当前文本：`"Sandbox: mit birne"`。
- 内部规则 2 与“banane”不匹配。由于该组处于活动状态，因此它会回退到附加 `"banane"` -> 当前文本：`"Sandbox: mit birne banane"`。
4. 最终文本“Sandbox: mit birne banane”由 LanguageTool 返回并纠正。
* 输出：`“沙盒：mit Birne Banane”`

* **场景 B（未触发宏 - 双倍可用性）**：
* 输入：`"ein apfel und eine kirsche"`
* 预期流量：
1. 起始规则不匹配。 “sandbox_test”组仍处于非活动状态。
2. 循环继续执行下一条规则。
3. **内部规则 1**：匹配 `"apfel"` 并将其替换为 `"birne"` -> 当前文本：`"ein birne und eine kirsche"`。
4. **内部规则 2**：不匹配。由于未触发该组，因此该规则的行为与正常的独立规则一样，**不会附加任何内容**。
5. 忽略结束规则。
* 输出：`“ein birne und eine kirsche”`

---

## 技术细节（底层）

* **隔离递归**：当触发组时，引擎会使用“custom_rules=[inner_rule]”递归调用“process_text_in_background”。这允许每个内部规则在完整、同步的管道传递中执行。
* **性能和稳定性保障**：
* **序列绕过**：内部递归运行绕过`chunk_id`序列队列以防止死锁和执行延迟。
* **I/O 和 TTS 抑制**：递归运行抑制中间文件写入和 TTS 语音输出，确保仅写入和说出最终稳定的文本。
* **稳定性保障**：递归运行在一次迭代后严格中断，以防止回退追加期间出现无限稳定性循环。
* **安全终止**：稳定性检查严格依赖于最大迭代计数（MAX_ITERATIONS_FOR_SAFETY）来防止无限循环，绕过基于时间的限制，该限制可能会过早中止合法的、较慢的宏执行。
__代码_块_4__