Skip to main content

dsh-tool-regex/packages/dsh-tool-regex

24Stars1Forks1Issues0Watchers

Provides regex pattern matching, validation, and replacement operations for text processing.

Categories⇄ Integrations
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the omdsh-dev/dsh-toolkit monorepo — stars and activity count the whole repository.

omdsh-devomdsh-dev
·omdsh-dev/dsh-toolkit
Language
TypeScript
License
MIT
Branch
main
collectiondshdsh-plugintoolkitzero-dependency

Install

cmdweb profile
$ dsh plugin --profile web add github:omdsh-dev/dsh-toolkit#path:packages/dsh-tool-regex

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin omdsh-dev/dsh-toolkit/packages/dsh-tool-regex for me: review the repository at https://github.com/omdsh-dev/dsh-toolkit first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

一句话定位

dsh-tool-regex 为 DSH 助手提供一组零依赖的正则操作：测试匹配、提取捕获组、安全替换，并能静态解释正则含义（不执行代码）。它把易出错的"心算正则"换成可验证、可限时的工具调用，从源头规避灾难性回溯（ReDoS）阻塞宿主。

核心能力

  • 测试文本是否匹配给定正则（test），整串语义由调用方用 ^...$ 锚点表达
  • 提取文本中所有匹配的位置、完整匹配、编号捕获组与命名捕获组（find，未传 g 时自动补 g）
  • 对文本执行全局安全替换，支持 $1/$<name>/$$ 等原生引用语法（replace）
  • 静态解析正则结构，把 pattern 拆成人读节点序列输出，不构造 RegExp、不执行匹配（explain）
  • 多层资源防护：输入/pattern/replacement/输出字节上限 + find 匹配数钳制 + worker 硬超时

技术实现

  • 语言: TypeScript（零运行时依赖，纯函数 + Node 内置 node:worker_threads）
  • 关键依赖: node:worker_threads（隔离执行线程）、@deepseek-ai/dsh-tools（defineTool 工具定义）、@deepseek-ai/cordis（宿主注入）
  • 架构模式: 通过包内 cordis.patch.yml 将插件插入 profile 的 layer stack（row id tool-regex），注册名为 regex 的工具；test/find/replace 派发到 Worker 线程执行（WORKER_BUDGET_MS = 1000ms 超期强制 terminate()），explain 走主线程同步静态 tokenizer
  • 入口文件: src/index.ts（apply(ctx) 钩子）

适用场景

当模型需要验证一条正则、解析日志字段、抽取捕获组或执行文本替换时使用本插件，避免模型"心算"正则出错率高、用户不可验证的痛点。它尤其适合处理用户给出的 pattern（先 explain 让用户看清含义，再 test/find 验证），以及需要 $1/$<name> 引用语法的批量重写场景。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.8已在 @deepseek-ai/[email protected] 隔离 consumer 中完成全链路验证
Node.js22.19.0 或 ≥24.0.0engines.node 声明 ^22.19.0 || >=24.0.0
@deepseek-ai/cordis^4.0.1peer 依赖，由宿主提供
@deepseek-ai/dsh-tools≥0.0.1-rc.1 <0.2.0peer 依赖，提供 defineTool
@deepseek-ai/dsh-invariants≥0.0.1-rc.1 <0.2.0peer 依赖
平台跨平台无 os/cpu 字段限制
原生模块node:worker_threadsNode 内置，无需额外编译

安装方式

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

配置项

本插件无需额外配置。安装后插件自动注册 regex 工具，无需读取配置文件或环境变量。所有可调参数均通过工具调用本身的 flags、replacement、limit 字段在每次调用时传入。

常见问题

Q: 这个插件需要任何配置吗？

A: 不需要。安装完成后插件会自动注册到 profile 层，工具即可直接调用，无需编辑配置文件或设置环境变量。

Q: 和系统的 grep 命令有什么区别？

A: grep 是文件域搜索且需启动 shell 进程；本插件接受任意文本字符串作为输入，可以提取捕获组、执行替换，还能静态解释正则结构。速度更快、不依赖文件、不污染宿主环境。

Q: 病理正则（如 (a+)+）会不会卡死助手？

A: 不会。test/find/replace 跑在独立 worker 线程中，1000ms 到期即强制 terminate() 并返回错误；explain 完全不构造 RegExp、走静态扫描，天然免疫回溯。

Q: 输入大小有上限吗？

A: 有。入口硬上限：待匹配文本 ≤ 64KB、pattern ≤ 16KB、replacement ≤ 16KB、输出 ≤ 1MB、find 报告匹配数 ≤ 1000。超限会直接拒绝（不截断）。

Q: explain 动作和其他三个动作有什么不同？

A: explain 只把正则字符串拆成节点（字面量、字符类、量词、锚点等），返回人读解释，完全不执行匹配；test/find/replace 则会真实跑匹配并返回结果。explain 是验证"这条正则到底长什么样"的安全手段。

Q: replace 支持哪些替换引用语法？

A: 支持 JS 原生 $-语义：$$ → 字面 $，$1/$2 → 编号捕获组，$<name> → 命名捕获组。未知引用按 V8 行为字面保留。实现走 String.replace 的字符串替换路径，不会执行代码。

Q: 怎么卸载？

A: 通过 profile 的 bundle 层管理移除：在对应 profile 中删除 row id tool-regex，或使用 dsh plugin --profile web remove 命令。

Q: 安装命令中的 --profile web 是什么意思？

A: DSH 用 profile 区分交互式（web）和一次性任务（headless）环境。web 用于交互式 UI，headless 是 dsh run 的默认 profile。两者独立，需要分别安装。

上手难度

入门 — 调用接口只需传 action + pattern + input 三参数，所有安全边界和超时已内置，无需任何额外配置或学习成本。

已知问题与限制

  • 资源硬上限：输入 64KB / pattern 16KB / replacement 16KB / 输出 1MB / find 匹配数 1000，超限会被拒绝（src/engine.ts:22-27）
  • find 的 limit 默认 50，最多 1000（src/engine.ts:30,67），超出钳制而非报错
  • test/find/replace 的总执行时间硬上限 1000ms（src/index.ts:27），超时返回错误而非截断结果
  • 对"无锚点的嵌套量词 + 不可信大输入"组合存在原生 ReDoS 风险，README 明确要求模型对此类 pattern 保持警惕（README.md:24）
  • explain 节点数 ≤ 4096，超限返回 regex: explain: pattern too complex（src/engine.ts:27）

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-toolkit/packages/dsh-tool-regex)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory