dsh-semver-toolkit

零运行时依赖的语义化版本（SemVer 2.0.0）工具集，用于 DeepSeek Harness 生态：解析/校验版本号（含 prerelease、build 元数据）、按规范优先级规则精确比较与排序、npm 风格版本范围匹配（^ ~ > < x-range hyphen ||）与最高满足版本查找。不依赖任何第三方库，仅用 Node 内置模块。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-semver-toolkit
• npm：https://www.npmjs.com/package/dsh-semver-toolkit
• 协议：MIT

功能说明

• parse_version：解析一个或多个版本字符串。拆出 major/minor/patch、prerelease 标识符列表、build 元数据；校验合法性（前导零、三元组完整性、prerelease 标识符规则）并给出失败原因；支持 v / = 前缀容错；可选按级别递增（major / minor / patch / prerelease）。
• compare_versions：精确比较与排序。实现 SemVer 2.0.0 完整优先级：三元组逐项数值比较 → prerelease 标识符逐个比较（数字标识符按数值、字母数字按字典序、数字 < 字母数字、前缀相同则短者小、无 prerelease 高于有）；build 元数据不参与比较。
• satisfies_range：npm 风格范围匹配，输出每个版本的命中详情与最高满足版本（maxSatisfying）。支持：
  • 精确：1.2.3 / =1.2.3
  • 比较：>1.2.3 >=1.2.3 <1.2.3 <=1.2.3（partial 进位：>1.2 → >=1.3.0、<=1.2 → <1.3.0）
  • caret：^1.2.3 → >=1.2.3 <2.0.0，含 ^0.2.3 → <0.3.0、^0.0.3 → <0.0.4 的 0 锁定规则
  • tilde：~1.2.3 / ~1.2 → >=1.2.0 <1.3.0，~1 → <2.0.0
  • x-range：1.2.x / 1.2.* / 1.2 / 1
  • hyphen：1.2.3 - 2.3 → >=1.2.3 <2.4.0
  • 或：^1 || ^2 多组并集；空格 AND 交集
  • prerelease 默认排除（除非范围本身含同三元组 prerelease），可 include_prerelease 开启

安装

# 从 npm 安装
dsh plugin --profile web add dsh-semver-toolkit

# 本地开发调试（Debug patch）
# 新建 debug.patch.yml：
# - insert:
#     - id: semver-toolkit
#       name: "E:/dsh-plugins/dsh-semver-toolkit/index.js"
dsh web --patch ./debug.patch.yml

使用说明

1. parse_version —— 解析与校验

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | versions | string | 是 | 版本字符串，多个用逗号或空格分隔 | | bump | string | 否 | 递增级别：major / minor / patch / prerelease |

2. compare_versions —— 比较与排序

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | versions | string | 是 | 版本字符串列表 | | order | string | 否 | asc（默认）/ desc |

3. satisfies_range —— 范围匹配

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | range | string | 是 | 版本范围，如 ^1.2.3、1.2.3 - 2.0.0、^1 \|\| ^2 | | versions | string | 是 | 候选版本列表 | | include_prerelease | boolean | 否 | 是否允许匹配 prerelease，默认 false |

典型场景

• 依赖升级决策：一堆候选版本里找出 ^1.2.0 能吃到的最高版本，判断升级是否跨越破坏性变更。
• 版本号校验：发布前校验 tag/包名里的版本号是否符合 SemVer（前导零、缺段、非法 prerelease 一眼看出）。
• 发版递增：bump=minor 直接给出下一个版本号；prerelease 阶段 patch 递增会归位不进位。
• 范围理解：^0.2.3 到底覆盖哪些版本？工具直接展开成 >=0.2.3 <0.3.0 并逐个标注命中情况。

安全边界

• 纯计算：无文件读写、无网络请求、无副作用。
• 严格遵循 SemVer 2.0.0：默认拒绝前导零（01.2.3）与不完整三元组（1.2），解析失败给出具体原因而非模糊报错。
• prerelease 匹配默认排除，避免 ^1.2.3 意外吃到 2.0.0-rc.1 这类不稳定版本。
• 大列表无保护上限（纯内存比较），超大规模（万级）建议分批。

版本说明

| 版本 | 日期 | 说明 | |------|------|------| | 0.1.0 | 2026-10-16 | 首个版本：parse_version / compare_versions / satisfies_range，完整 SemVer 2.0.0 优先级链与 npm 风格范围匹配，74 断言测试（含官方 prerelease 优先级链） |

RoadMap

• [ ] loose 宽松模式（前导零、缺段补零、v1.2 等）
• [ ] includePrerelease 细粒度选项（npm 的 withPrerelease 语义）
• [ ] 从 package.json / lockfile 批量读取依赖版本并检查范围
• [ ] outside / diff：判断两个版本跨越的变更级别（major/minor/patch）
• [ ] changelog 版本号排序与去重

其他插件集成说明

• dsh-deps-audit：依赖审计管多版本冲突与未使用依赖；本插件提供版本解析与范围匹配的底层能力，两者可组合（先解析版本再判冲突范围）。
• dsh-git-helper：git 标签列表可交给本插件做 SemVer 校验与排序，找出下一个发版号。
• dsh-json-yaml-toolkit：读取 package.json 后交给本插件做版本检查。
• dsh-code-metrics / dsh-test-report：CI 流水线中用本插件校验产物版本与 tag 一致性。

FAQ

Q1：^0.2.3 为什么不匹配 0.3.0？ SemVer 约定 0 开头为开发期，caret 锁定左侧第一个非零位：^0.2.3 → >=0.2.3 <0.3.0（minor 非零锁 minor），^0.0.3 → <0.0.4（锁 patch）。

Q2：1.0.0-alpha 和 1.0.0-alpha.1 谁大？ 后者大。prerelease 前缀相同时，标识符更多的版本更大。完整优先级链（官方规范示例）：alpha < alpha.1 < alpha.beta < beta < beta.2 < beta.11 < rc.1 < 1.0.0。

Q3：为什么 ^1.2.3 不匹配 2.0.0-rc.1，即使开了范围？ npm 规则：带 prerelease 的版本默认只匹配范围中「三元组相同且自身含 prerelease」的比较器（如 ^1.2.3-alpha 可匹配 1.2.3-beta），跨三元组的 prerelease 一律排除；或显式传 include_prerelease。

Q4：build 元数据（+build.5）参与比较吗？ 不参与。1.0.0+build.1 与 1.0.0+build.99 相等，仅在解析结果中展示。

Q5：>1.2 的语义是什么？ 按 npm 规则展开为 >=1.3.0（partial 版本的 > 需进位到下一个未指定位），<=1.2 展开为 <1.3.0。

Q6：v1.2.3 能解析吗？ 能。v / V / = 前缀会被容错剥离并在结果中标注「已容错」。

许可证

MIT