Introduction

In a DSH workflow, models often need to perform matching judgments on text, extract fields, execute rule-based replacements, or explain the meaning of a pattern. If these operations are left to the model to “calculate” mentally, the results are hard to verify; if a process is spawned to write a script on the fly, it introduces additional overhead and risks regarding script correctness.

Below is an introduction to omdsh-dev/dsh-tool-regex. It is a DSH regex tool plugin maintained by omdsh-dev, providing capabilities for testing matching, extracting capturing groups, safe replacement, and static explanation of regex meaning, and unifying the output into a JSON text string.

Plugin Positioning

dsh-tool-regex is a DSH regex tool plugin: testing matching, extracting capturing groups, safe replacement, and static explanation of regex meaning (without executing any code). It has zero dependencies, uses pure functions, and is under the MIT license.

Repository URL:

https://github.com/omdsh-dev/dsh-tool-regex

Core Features

The plugin registers a regex tool, and the action can be one of the following values:

  1. test: Determine if it matches.
  2. find: Returns the index of all matches, the full match, numbered capturing groups captures, and named groups groups.
  3. replace: Global safe replacement, supporting $1, $2, $<name>, and $$.
  4. explain: Static parsing of the pattern structure to provide a human-readable explanation, without executing the match.

All these actions output a JSON text string uniformly.

Parameters and Limits

Basic parameters are as follows:

  • action: Optional values are test, find, replace, explain.
  • pattern: Uses JavaScript regex syntax, without surrounding /.
  • input: Used for test, find, replace.
  • replacement: Used for replace, supports $1, $2, $<name>, $$.
  • limit: Used for find, default 50, maximum 1,000.

Resource and timeout limits are as follows:

  • Max input length: 64,000 bytes (UTF-8).
  • pattern ≤ 16KB.
  • replacement ≤ 16KB.
  • Output ≤ 1MB.
  • find match count ≤ 1,000.
  • test / find / replace are executed in a killable worker, returning regex: execution timed out after the 1,000ms budget expires.
  • explain only performs static tokenization, does not construct a RegExp instance, and node count ≤ 4,096.

Security Boundaries

The documentation explicitly warns: Do not use unanchored nested quantifier patterns on untrusted large inputs.

The aforementioned worker hard timeout, input length limit, pattern / replacement / output / match count limits are the protection boundaries provided by the plugin. The plugin runs with the privileges of the current dsh process; you should check the source code and the MIT license before installation.

Installation and Usage

Install via the interactive web profile:

dsh plugin --profile web add github:omdsh-dev/dsh-tool-regex

After installation, first check if tool-regex appears in the profile configuration:

dsh --profile web --dump-config | grep tool-regex

The internal dsh.bundle.patch will add the plugin to the profile’s layer stack after installation, with a row id of tool-regex.

Note: web and headless are different profiles; web installation does not automatically overwrite headless; dsh run uses the headless profile by default.

Run verification:

dsh run "使用 regex 工具测试 d+ 是否匹配 abc123"

Typical Usage

find can be used to extract all matches, the full match, numbered capturing groups, and named groups. Documentation example:

regex { action: "find", pattern: "(\\w+)@(\\w+)", input: "a@b x c@d" }
→ [{"index":0,"match":"a@b","captures":["a","b"],"groups":null},{"index":6,"match":"c@d","captures":["c","d"],"groups":null}]

replace can be used for global safe replacement, supporting $1, $2, $<name>, $$. Documentation example:

regex { action: "replace", pattern: "(\\w+) (\\w+)", input: "hello world", replacement: "$2 $1" }
→ {"result":"world hello","replaced":1}

explain only statically parses the pattern without executing the match. Documentation example:

regex { action: "explain", pattern: "\\d{4}-\\d{2}" }
→ [{"kind":"escape","text":"\\d","meaning":"A digit [0-9]"},{"kind":"quantifier","text":"{4}",...},...]

Runtime Environment

The plugin requires Node engines:

^22.19.0 || >=24.0.0

Conclusion

dsh-tool-regex converges regex judgment, field extraction, safe replacement, and static explanation into a deterministic tool within DSH, suitable for scenarios where regex behavior needs to be verified within a DSH workflow.

GitHub URL:

https://github.com/omdsh-dev/dsh-tool-regex