dsh-tool-regex

English

DSH 正则工具插件 —— 测试匹配、提取捕获组、安全替换、静态解释正则含义（不执行任何代码）。零依赖、纯函数。

动机

模型经常需要验证用户给的 pattern、从日志/文本中提取字段、做文本替换。"心算"正则结果错误率极高，且无法给用户展示可验证的过程。现有替代是起 bash 进程跑 node -e 或 python——进程开销 + 模型现写脚本的正确性风险。内置 grep 只能做文件域搜索，无法对任意文本测试/提取/替换/解释。

本插件提供确定性正则工具，其中 explain 是差异化能力：静态解析 pattern 结构并给出人读解释，不执行匹配，天然免疫 ReDoS。

安全模型（ReDoS 多层防线）

JS 正则的灾难性回溯是真实威胁（如 (a+)+$ 配合超长输入）。防线：

1. worker 硬超时：test/find/replace 在可终止的 worker 线程内同步执行，1,000ms 预算到期 worker.terminate() 并返回 regex: execution timed out——灾难性回溯不再能阻塞宿主进程（工具管道的 timeoutMs 对同步阻塞体是协作式，仅靠它不够；worker 内会再次执行全部上限校验）
2. 输入长度上限：64,000 字节（UTF-8）——超限在入口直接拒绝，不进入回溯
3. 资源上限：pattern ≤ 16KB、replacement ≤ 16KB、输出 ≤ 1MB、匹配数 ≤ 1,000（limit 钳制）
4. explain 零执行：只做静态 tokenizer，不构造 RegExp 实例，任何 pattern 都即时返回

⚠️ 工具描述与 README 均明确警告模型：不要对不可信的大输入使用无锚点的嵌套量词 pattern（如 (a+)+、(.*)*）。

其余边界：无效 pattern 捕获 SyntaxError 报错（含位置信息）；无效/重复 flag 逐字符校验；replace 使用 String.replace 字符串替换路径（JS 原生 $-语义，无 new Function、无 eval）。

工具声明

注册 regex 工具（@deepseek-ai/dsh-tool-regex，row id tool-regex），统一输出 JSON 文本字符串。

参数	类型	必填	说明
action	string	✅	test / find / replace / explain
pattern	string	✅	正则（JavaScript 语法，不含外围 /）；≤ 16KB
input	string		待匹配文本（test/find/replace 必需）；≤ 64KB
flags	string		如 "gi"；支持 g i m s u y d v，需唯一且合法
replacement	string		replace 的替换文本，支持 $1/$2/$<name>/$$；≤ 16KB
limit	integer		find 最大报告匹配数，默认 50，上限 1,000

Actions

action	功能	输出示例
test	判断是否匹配（整串语义由模型自行用 ^...$ 表达）	{"matched":true}
find	全部匹配：index / 完整匹配 / 编号捕获组 captures / 命名组 groups（无 g 自动补 g）	[{"index":0,"match":"a@b","captures":["a","b"],"groups":{"name":"a"}}]
replace	全局安全替换（$1/$<name>/$$），返回结果与替换次数	{"result":"world hello","replaced":1}
explain	静态解析 pattern → 人读节点序列（不执行匹配；节点数 ≤ 4,096）	[{"kind":"escape","text":"\\d","meaning":"A digit [0-9]"}]

示例

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}]

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

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

边界行为

情况	处理
无效 pattern	regex: invalid pattern: <SyntaxError 信息（含位置）>，不崩溃
无效 flag / 重复 flag	regex: invalid flag "q" / regex: duplicate flag "g"
空 pattern	合法（匹配空串）；u/v 下空匹配按 code point 推进（surrogate pair 不会重复命中）
ReDoS（病理 pattern）	worker 硬超时：regex: execution timed out (1000ms)，宿主不阻塞
命名组 / 编号组	find 输出 groups: {name: value} 与 captures: [...]；replace 支持 $<name>/$n
零匹配	find 返回 []；replace 返回原文本 + replaced: 0
输入超 64KB / pattern 超 16KB / replacement 超 16KB	入口拒绝（不截断）
输出超 1MB（替换放大如 $`` / $'`）	regex: result/output exceeds 1000000 bytes，拒绝而非截断
find limit	默认 50，钳制到 1,000（防输出膨胀）
explain 节点超 4,096	regex: explain: pattern too complex
$ 引用	走 JS 原生字符串替换路径：$$→$、$n→组（未参与→空串）、$<name>→命名组、未知引用字面保留（$0/$<foo> 与 V8 一致）

npm rc.1 兼容（已验证）

本插件已迁移到 npm rc.1 依赖线，并在 @deepseek-ai/dsh@0.0.1-rc.1 的隔离 consumer 中完成全链路验证：

• 类型/运行时：@deepseek-ai/cordis@^4.0.1-rc.1 + @deepseek-ai/dsh-tools@^0.0.1-rc.1 + @deepseek-ai/dsh-invariants@^0.0.1-rc.1（peer）；不再依赖 unscoped cordis
• 独立构建：npm install（devDependencies 自包含 typescript/vitest/@types/node）→ npm run typecheck → npm test → npm run build → npm pack
• 消费验证：tarball 装入 rc.1 consumer → dsh --profile compat --dump-config 出现本插件 row → 工具真实注册与执行通过
• 启动方式：npx -p @deepseek-ai/dsh@0.0.1-rc.1 dsh web（lib 生产模式；勿 install -g 全局安装）

安装

Profile Bundle（推荐）

将本插件作为独立 bundle 安装到 profile（0806+）：

# 交互式（web）profile
dsh plugin --profile web add "C:/path/to/dsh-tool-regex"
# 一次性任务（headless）profile —— dsh run 默认使用 headless
dsh plugin --profile headless add "C:/path/to/dsh-tool-regex"

包内 dsh.bundle.patch 会在安装后自动把插件加入 profile 的 layer stack（row id：tool-regex）。插件缺失的 peer 依赖（cordis、@deepseek-ai/dsh-tools）由 profile 的 healed profiles/node_modules 回退安装提供。

⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。Windows 路径使用正斜杠（C:/...）。

验证安装

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

运行验证

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

手动安装与旧版本兼容

仅适用于不支持 Profile Bundle 的旧快照或插件开发调试环境（本地 junction/symlink、手动编辑 profile 层）。

测试

node <monorepo>/node_modules/vitest/vitest.mjs run tests

• engine.spec.ts：test/find/replace 全分支 + flags/pattern 错误 + 64KB 上限 + ReDoS worker 用例（病理 pattern 在 3s 预算内被取消，不挂死测试进程）
• explain.spec.ts：字面量/字符类/分组/量词/转义/锚点/交替 + 未闭合报错
• register.spec.ts：注册契约（AUDIT-CROSS-02 风格）

许可

MIT