深鲸发版守卫（dsh-release-guard）

不装会怎样

发版前靠人肉核对：package.json 改了、锁文件忘了；CHANGELOG 还是上一版；下载页写着旧版本号； 流水线里 RELEASE_VERSION=0.9.0 还硬编码着。等到用户装上发现版本对不上、商店页写着上个月的号，已经发出去了。

这个插件把「现在能不能发、还差什么」变成一条命令。

它做什么

• 六项检查，每项给结论 + 证据：版本一致性（package.json ↔ lock）、tag 与远端状态、CHANGELOG/更新说明是否覆盖本版本、站点/前端文件里的版本号、发版流水线里是否有硬编码旧版本号、可选查 registry 是否已发布。
• 三种输出：人读文本；--json 机器可读；退出码 0 可发 / 1 有阻断 / 2 只有警告 —— 直接能塞进 CI 或发版脚本。
• 判据可配置：仓库根放 .release-guard.json 就能改站点文件 glob、CHANGELOG 路径、tag 前缀等，不用改代码，也不写死任何项目路径。
• 只读、默认不联网：不写任何文件；只有加 --npm 才请求一次 registry，且只读。
• 带面板：侧栏「深鲸发版守卫」，填仓库路径点检查，逐项列证据与建议动作。

安装

dsh plugin --profile web add @deepwhale-cn/dsh-release-guard

装好后：侧栏出现「深鲸发版守卫」面板；也可以直接用命令行：

dsh-release-guard /path/to/repo          # 人读
dsh-release-guard /path/to/repo --json   # 机器可读
dsh-release-guard /path/to/repo --npm    # 额外查 registry（联网）
echo $?                                  # 0 可发 / 1 有阻断 / 2 只有警告

判据怎么配

默认值只写通用约定（不认识任何具体项目）。仓库根可放 .release-guard.json，字段与默认值：

{
  "versionFile": "package.json",
  "lockFiles": ["package-lock.json", "npm-shrinkwrap.json"],
  "changelog": "CHANGELOG.md",
  "notesFiles": ["assets/whatsnew.json", "whatsnew.json"],
  "siteVersionGlobs": ["index.html", "docs/**/*.html", "public/**/*.html"],
  "workflowGlobs": [".github/workflows/*.yml", ".github/workflows/*.yaml"],
  "tagPrefixes": ["v", ""],
  "ignoreDirs": ["node_modules", ".git", "dist", "build", "out", ".next", "coverage", "vendor"]
}

• 不用 CHANGELOG 的仓库："changelog": null。
• 站点版本文件在别处：改 siteVersionGlobs（glob 支持 **、*、?）。
• 只认 1.2.3 不认 v1.2.3：把 tagPrefixes 改成 [""]；两种都认就留着默认。

自测

bash tests/run.sh

三个临时仓库 fixture（不碰本机任何真实仓库、不联网）：干净仓库必须 0 阻断 0 警告；脏仓库必须 ≥3 阻断且证据带具体版本号；只有警告的仓库退出码必须是 2。

边界（已知限制）

• 只读本机 git，不做 git fetch，也不联网（--npm 除外）：远端是否已推送，只能依据本地已有的 origin/<branch> 引用；没 fetch 过会给出警告而不是猜。
• 「流水线硬编码」按版本族判定，只报「自己漏改的旧版本」：当前 1.0.64 时只把 1.0.x 的旧字面量算阻断（1.0.17 这种）；electron 43.4.0、随包运行时 0.2.0-rc.2 这类别的版本族只忽略不报。此外会跳过纯注释行、@v4.1.0 这类 action 引用、node-version/DSH_/runtime 等运行时行，并要求字面量处在版本语境（version/tag/release/产物名 .exe/.deb/.dmg 等）里。所以这条规则在别的项目上同样成立，不是给某个项目开特例。
• 「站点版本」按 siteVersionGlobs 命中文件里的 x.y.z 字面量：文件里出现当前版本即通过；只出现别的版本才报「站点版本不一致」。站点里如果同时列着多个历史版本的下载链接，需要把这类文件从 glob 里排除。
• 更新说明（notesFiles）支持多种形状：条目数组 [{version}]、{versions:{...}}、{releases:[...]}、顶层平铺 {"1.2.3":{}}；_comment 之类以 _ 开头的键忽略，键名不会被当成版本号剥前缀。
• 不判断代码质量、不跑测试、不构建：它只管「发版元数据与文件是否自洽」。
• 只支持 npm 系锁文件（package-lock / npm-shrinkwrap）；pnpm / yarn 的锁文件可按需自行扩展 lockFiles（结构不同，当前不解析）。

本插件是一个工具。使用者必须遵守所在地区法律法规，对使用本项目造成的任何后果自行承担责任。

---