# Regex

## 这是什么?

Regex 扩展允许用户自动检测文本字符串中的特定模式(称为"序列")并对其应用操作(替换)。当与其他 SillyTavern 功能(如[快速回复或 STscript](/For_Contributors/st-script.md))结合使用时，它可以成为一个强大的工具，或者简单地作为从聊天中删除某些单词的方法。

## 有用的链接

**本文档不会深入解释编写 RegEx 序列的过程。有许多在线资源可以帮助您。**

- [https://regexr.com](https://regexr.com)

- [https://regex101.com](https://regex101.com)

- [https://extendsclass.com/regex-tester.html](https://extendsclass.com/regex-tester.html)

- [https://en.wikipedia.org/wiki/Regular_expression](https://en.wikipedia.org/wiki/Regular_expression)

## 前置条件

Regex 是 SillyTavern 的内置扩展，因此不需要额外的设置。

您可以在 **<i class="fa-solid fa-cubes"></i> 扩展** 面板中找到其设置。

## 常见用例

RegEx 通常用于对聊天中的某些单词应用查找-替换功能，为某些单词或句子类型添加 markdown 样式，或向 STscript 返回布尔值。

## 脚本列表

![RegEx 扩展脚本列表](/static/extensions/regex-listview.png)

- 顶部的按钮用于创建新脚本。
  - "全局"脚本将应用于所有角色，并将保存到 `settings.json` 中。
  - "作用域"脚本仅应用于当前活动角色，并将保存到角色卡的数据中。
- "导入"允许您导入从另一个 SillyTavern 实例导出的 RegEx 脚本。

下面是您的脚本列表以及一些操作按钮。

- 拖动手柄(脚本名称左侧的三个水平条)允许您将脚本拖放到任何您喜欢的顺序。
- 主开关可以快速切换以启用或禁用脚本，而无需更改其他任何内容。禁用的脚本以~~删除线~~样式显示。**如果在此处禁用脚本，则快速回复或 STscript 将无法触发它。**
- "编辑"(铅笔)按钮将打开 RegEx 脚本编辑器。
- "移动到作用域"(向下箭头)将全局脚本转换为作用域脚本并将其应用于当前角色。反之(向上箭头)将作用域脚本转换为全局脚本。
- "导出"将导致您的浏览器下载脚本的导出 `.json` 文件，然后可以共享并导入到另一个 SillyTavern 实例中。
- "删除"(垃圾桶)删除脚本。

## RegEx 编辑器

![RegEx 编辑器](/static/extensions/regex-editor.png)

- **测试模式**:这将在编辑器顶部打开一个比较视图。在"输入"框中键入一些文本，您的 RegEx 脚本的结果将显示在输出框中。这是一个有价值的调试工具，因为它会在您对脚本设置进行更改时实时更新输出框。

- **名称**:扩展的脚本列表上显示的脚本标签。**这也用于在通过斜杠命令或 STscript 触发脚本时定位脚本。**

- **查找 Regex**:这是用于检测目标文本模式的正则表达式。这通常是任何 RegEx 脚本中最复杂的部分，也是最容易出错的地方。请参阅页面顶部的链接了解如何编写 RegEx 序列的信息。如果"查找 Regex 中的宏"设置为这样做，此框可以解析[常见的 SillyTavern 宏](/Usage/Characters/macros.md)(如 \{\{user\}\}、\{\{char\}\} 等)的值(见下文)。

- **替换为**:这将替换匹配的序列。在一个非常简单的例子中，如果您的"查找 Regex"是 `apple`，而您的"替换为"是 `orange`，那么在应用脚本的任何文本中，"apple"的第一次出现将自动更改为"orange"。

  - 在此框中添加扩展特定的宏 \{\{match\}\} 将插入完整匹配的文本序列。这通常用于对特定单词应用样式。回到上面的例子，如果将 \*\*\{\{match\}\}\*\* 放入"替换为"框中，则所有出现的单词"apple"将被替换为 `**apple**`，这将对其应用粗体 markdown 样式。

  - 可以使用变量 $1、$2、$3 等来插入所谓的"捕获组"。这些是由"查找 Regex"序列匹配的文本序列中的子字符串。**请注意，使用这些变量需要匹配表达式包含一组括号来定义匹配字符串的哪一部分算作捕获组。** 有关如何设置捕获组的参考，请参阅顶部的链接。

- **修剪**:放入此框的文本将在应用"替换为"过程之前从匹配的文本序列中删除。例如，如果我们的匹配是"apple"，修剪框包含"le"，那么在应用"替换为"过程之前，字母"le"将首先被删除。由于我们的"替换为"框包含 \*\*\{\{match\}\}\*\*，它将导致 `**app**` 被放入作为"apple"的替换(首先删除"le"，并且剩余的匹配文本被赋予粗体 markdown 样式)。可以通过在要删除的每个字符串之间添加换行符来应用多个修剪。

- **影响**:此复选框列表定义将应用 RegEx 脚本的文本源。
  - "用户输入":脚本将在用户点击发送后针对用户键入的输入内容运行。
  - "AI 响应":脚本将在收到 AI 响应的内容后针对其运行。
  - "斜杠命令":脚本将针对斜杠命令插入提示/聊天中的值运行。
  - "世界信息":脚本将在世界信息条目注入提示时针对其内容运行。**需要勾选"更改传出提示"(或取消勾选两个临时性复选框)。**
  - "推理":脚本将针对 Gemini 或 Deepseek 等聊天完成 API 返回的"推理"对象的内容运行。如果在临时性下勾选了"更改传出提示"，脚本还将应用于在后续聊天轮次中添加到提示中的任何推理块。
  - **如果这里的所有内容都未勾选，脚本将永远不会在正常聊天期间激活，但仍可以通过斜杠命令或 STscript 激活。**

- **其他选项**:
  - "禁用"可防止脚本运行。当您只是不想更改脚本的任何设置和/或不想通过脚本列表上的开关完全禁用它时(因为这样做会阻止斜杠命令触发它)，这将用作覆盖以防止脚本运行。
  - "编辑时运行"使脚本在编辑聊天消息后也运行。如果未选中此项，编辑的聊天消息的内容将不会触发脚本。

- **查找 Regex 中的宏**:选择是否替换"查找 Regex"框序列中存在的宏(如 \{\{user\}\}、\{\{char\}\} 等)。
  - "不替换"将导致任何 SillyTavern 宏被忽略，因此 RegEx 脚本在搜索时将按字面意思处理它们。
  - "原始"将逐字发送宏的值。如果宏的值包含某些特殊字符，这可能会改变 RegEx 脚本搜索文本的方式。
  - "转义"将在每个字符前添加 RegEx 转义斜杠 `\`，以确保它们不会意外改变整体 RegEx 序列。如果宏的值中有某些特殊字符，这可能很有用。

### 深度设置

最小/最大深度设置提供对 regex 模式将影响聊天历史中哪些消息的精确控制:

- **最小深度**:仅影响聊天历史中至少 N 级深度的消息
  - 0 = 最后一条消息
  - 1 = 倒数第二条消息
  - 等等
  - 当为空(设置为"无限制")或 -1 时，也将影响"继续"操作上要继续的消息

- **最大深度**:仅影响聊天历史中深度不超过 N 级的消息
  - 必须大于最小深度才能应用 regex
  - 系统提示和实用程序提示不受这些设置的影响

例如，将最小深度设置为 0，最大深度设置为 2，将仅将您的 regex 应用于聊天中最近的三条消息。

### 标志

默认情况下，查找 Regex 模式区分大小写，并且仅应用于第一个匹配项。要调整此行为以及其他 RegEx 标志，您可以像这样添加它们:

```txt
/yourpattern/flags
```

示例:`/yourpattern/gi` 将匹配文本中"yourpattern"的所有实例，无论大小写。

一些最常见的标志是:

- `i`:不区分大小写
- `g`:全局(应用于所有匹配项，而不仅仅是第一个)
- `s`:dotAll(将输入视为单行，因此 `.` 将匹配换行符)
- `m`:多行(将输入视为多行，因此 `^` 和 `$` 匹配每行的开始/结束，而不仅仅是整个字符串)
- `u`:unicode(将输入视为 unicode，因此 `\d`、`\w` 等将匹配 unicode 字符)

有关 RegEx 标志的更多信息，请参阅以下 MDN 页面:[使用标志进行高级搜索](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags)

### 临时性

默认情况下(当这里的两个框都未勾选时)，RegEx 脚本将直接编辑存储在聊天的 JSONL 文件中的文本值。这确保传出提示和聊天显示将始终包含相同的值。但是，对聊天文件的这些更改是不可逆的。

如果您不希望发生这种情况，可以启用此处的任一复选框，将 RegEx 脚本的影响限制为仅显示或传出提示。

如果只勾选了其中一个框，则不会对聊天文件进行任何更改，但**只有勾选的项目**会被更改。这意味着您将看到一件事，但 LLM 将看到另一件事。请谨慎使用。

如果两者都选中，脚本将以所有方式正常运行，除了它不会将任何更改写入聊天文件。

## 高级用法

虽然 RegEx 通常用作简单的查找/替换工具，但它也可以以更复杂的方式使用。

例如，"替换为"框可以包含一组 CSS 规则和 HTML，以在找到某个单词时将特定样式的 HTML 元素添加到您的聊天中。这将需要在用户设置面板中取消勾选 `在响应中显示 <标签>` 框。

脚本也可以设置为在正常使用期间永不触发，但可以通过斜杠命令作为 STscript 内部逻辑检查的一部分触发。"替换为"框将包含脚本识别的唯一值，以指示逻辑检查是真还是假。这将 RegEx 的实用性扩展到所有斜杠命令的完整功能，允许根据聊天内容实现真正无限级别的控制和自动化。