SearchReplaceText 多行文本查找与替换节点

节点核心功能 (What is it?)

SearchReplaceText 节点允许创作者对多行长文本内容执行精准的查找与替换操作。它不仅原生支持字面量纯文本匹配替换，还全面支持基于正则表达式（Regex）的高级模式检索与批处理替换。

典型适用场景 (When would I use it?)

在以下情况下使用 SearchReplaceText 节点：

• 通过替换特定模板占位符或特定字符串来动态修改多行文本；
• 执行区分大小写或忽略大小写的灵活文本替换；
• 使用正则表达式处理复杂的模式提取、格式清洗与结构化脱敏；
• 自由切换全局全量替换（Replace All）与首处匹配替换（First Match）；
• 深度处理跨越多行或包含多段落的复杂长文本。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

1. 在工作流画布中添加 SearchReplaceText 节点。
2. 连接上游文本或直接在 input_text 输入框中填入母文本（支持多行长文）。
3. 在 search_pattern 中设定待检索的目标字符串或正则表达式。
4. 在 replacement_text 中设定替换后的目标内容。
5. 按需勾选大小写敏感度、正则模式以及替换范围等参数开关。
6. 将清洗或替换完成的 output 连入下游文本消费节点。

参数输入插槽 (Parameters)

• input_text：执行查找与替换操作的原始母文本（string，支持多行文本）。
• search_pattern：待查找的目标纯文本关键词或正则表达式模式串（string）。
• replacement_text：用于填补替换的新文本内容（string，支持多行文本）。
• case_sensitive：是否严格区分大小写（布尔值，默认值：true）。
• use_regex：是否将查找模式解析为正则表达式（布尔值，默认值：false）。
• replace_all：是否替换所有匹配项；若关闭则仅替换首次出现的匹配项（布尔值，默认值：true）。

输出引脚 (Outputs)

• output：完成查找替换与排版处理后的全新文本字符串工件（string）。

典型示例 (Examples)

1. 基础纯文本替换 (Simple Text Replacement)

1. 在画布中添加 SearchReplaceText 节点。
2. 将 input_text 设为：

   Hello World
   Welcome to Griptape
   

3. 将 search_pattern 设为 "World"。
4. 将 replacement_text 设为 "Griptape"。
5. 节点输出结果：

   Hello Griptape
   Welcome to Griptape
   

2. 忽略大小写替换 (Case-Insensitive Replacement)

1. 添加 SearchReplaceText 节点。
2. 输入文本：

   Hello WORLD
   Welcome to the WORLD
   

3. 查找模式为小写 "world"，替换文本为 "Griptape"。
4. 将 case_sensitive 设为 false。
5. 节点输出结果：

   Hello Griptape
   Welcome to the Griptape
   

3. 正则表达式高级范例 (Regular Expression Examples)

基础正则匹配与替换

输入文本: "Line 1\nLine 2\nLine 3"
查找模式: "Line \\d"
替换文本: "Item"
启用正则 (use_regex): true
输出结果: "Item\nItem\nItem"

该模式能够精准匹配以 "Line " 开头紧跟任意一位数字（\d）的内容。

批量剔除数字符号

输入文本: "Product123, Item456, Order789"
查找模式: "\\d+"
替换文本: ""
启用正则 (use_regex): true
输出结果: "Product, Item, Order"

利用 \d+ 模式一键剥离连续的一个或多个数字。

单词边界精确匹配 (Word Boundaries)

输入文本: "cat in the hat"
查找模式: "\\bcat\\b"
替换文本: "dog"
启用正则 (use_regex): true
输出结果: "dog in the hat"

利用 \b 单词边界锚点，确保仅匹配独立的单词 "cat"，绝不误伤 "catch" 或 "scatter"。

整行多行匹配

输入文本: "First line\nSecond line\nThird line"
查找模式: "^.*$"
替换文本: "New line"
启用正则 (use_regex): true
输出结果: "New line\nNew line\nNew line"

匹配每一行的起始（^）、任意字符序列（.*）直至行尾（$）。

正则表达式快速参考 (Regex Reference)

常用正则表达式速查

模式	语义说明	示例
\n	匹配单个物理换行符	Line 1\nLine 2
\s	匹配任意空白字符（空格、制表符等）	Hello\sWorld
\d	匹配任意单精度阿拉伯数字	\d+ 匹配 "123"
[a-z]	匹配任意单个小写英文字母	[a-z]+ 匹配 "hello"
[A-Z]	匹配任意单个大写英文字母	[A-Z]+ 匹配 "WORLD"
.	匹配除换行符外的任意单个字符	a.c 匹配 "abc"
*	匹配前导字符 0 次或多次	a* 匹配 "", "a", "aa"
+	匹配前导字符 1 次或多次	a+ 匹配 "a", "aa"
?	匹配前导字符 0 次或 1 次	a? 匹配 "", "a"
\b	匹配单词边界锚点	\bcat\b 匹配 "cat" 而不匹配 "catch"

正则模式转义安全须知

当开启 use_regex: true 模式时，查找模式中的所有特殊字符均会被视作正则操作符。若需字面量匹配这些字符，请务必使用反斜杠执行转义（例如 \. 或 \?）。

字面量纯文本模式的便利性

当关闭正则模式（use_regex: false）时，输入的所有查找字符均会被纯文本原样解析，特殊字符会被底层自动转义处理，对于常规的关键词替换既直观又安全。

关键技术特性 (Important Notes)

• 使用正则表达式模式时，请务必保证对转义字符的合规处理；
• 大小写不敏感匹配无论在普通字面量模式还是正则模式下均能正常生效；
• 若未在输入文本中检索到任何符合条件的匹配项，节点将安全地原样返回原始文本；
• 正则表达式语法非法时，节点具备安全容错机制，将直接返回原文本而不抛出崩溃异常；
• 输入与输出文本的内部原始换行排版均会被忠实保留；
• 在正则模式下，可以直接在查找模式中写入 \n 来跨行匹配换行位置。

常见问题与排查 (Common Issues)

• 正则表达式语法报错：请核查开启 use_regex 后是否存在未闭合的括号或非法正则限定符。
• 超大规模长文本性能波动：在数十万字的长篇文本上执行带有复杂回溯的正则表达式可能导致处理耗时增加，建议优化正则式减少贪婪匹配。
• 换行符识别异常：若需字面量跨行匹配，请注意不同操作系统下 \r\n 与 \n 的差异。